@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.
Files changed (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
package/README.md CHANGED
@@ -1,266 +1,304 @@
1
- # OATS: an open framework for specialised agent teams
1
+ # OATS
2
2
 
3
- **Free, open source, provider- and harness-agnostic, and decentralised by design.**
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
- > **Coding agent setting up OATS for someone?** Go to [Start here](#start-here): it tells you what to download and run next.
5
+ [![Release](https://img.shields.io/github/v/release/oats-project/oats?display_name=tag)](https://github.com/oats-project/oats/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
6
 
7
- [![npm version](https://img.shields.io/npm/v/@awebai/oats.svg)](https://www.npmjs.com/package/@awebai/oats)
8
- [![Release](https://img.shields.io/github/v/release/awebai/oats?display_name=tag)](https://github.com/awebai/oats/releases)
9
- [![Node 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
10
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+ Free and open source.
11
8
 
12
- OATS—**Open Agent Team Specification**—is a provider- and harness-agnostic framework for building distributed agent teams: on one laptop, across machines or across a large organisation, as flexibly as you need. It is completely free and open source.
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
- - **Every agent keeps the full power of its harness.** Claude Code, Codex or pi: OATS connects them, so agents on different harnesses and providers communicate and work together.
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
- For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has its own for its area. Through capabilities you decide:
13
+ **OATS is a framework for building agent teams that are provider and model agnostic.** It has two parts:
21
14
 
22
- - which specialists make up the team;
23
- - which models and harnesses their instances use;
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
- The [official catalog](docs/official-catalog.md) is the reviewed list of official packages. A workspace trusts a package by declaring it; being listed doesn't declare it.
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
- ## Start here
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
- As model providers expand into complete agent platforms, choosing a model can also mean adopting that provider’s memory system, tools, workflows and communication channels. We wanted those to remain separate choices.
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
- **We believe machine intelligence should become a commodity:** available from different providers through open interfaces, including local models that individuals can run and control themselves.
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
- Models will still differ. But changing one should not mean abandoning the expertise, knowledge and working practices you have built around it.
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
- OATS is our attempt to make that world practical.
28
+ ## A new way to think about agents
66
29
 
67
- ## Souls and instances
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 separates an agent’s reusable specialisation from the particular work it is doing.
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
- ### A soul defines a kind of expert
34
+ ## The building blocks
72
35
 
73
- A **soul** is a reusable, versioned agent definition. It establishes:
36
+ Each block uses the ones before it.
74
37
 
75
- - Its expertise and responsibilities.
76
- - Its boundaries and operating principles.
77
- - Its capabilities and specialised skills.
78
- - The knowledge it should consult.
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
- A soul is not a model or a conversation. It is the definition from which working agents are created. A UX-expert soul, for example, might combine interaction-design principles, accessibility skills and access to accepted product knowledge.
46
+ ### An instance's home
81
47
 
82
- ### An instance does the work
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
- An **instance** is one incarnation of a soul, with its own identity, assignment, working context and state. It runs through a **harness**—the agent application, such as Pi, Claude Code or Codex—using the selected model.
85
-
86
- Instances can have different lifetimes:
87
-
88
- - **Short-lived instances** handle bounded work. For example, we use ephemeral developer and reviewer instances to implement and review specific changes.
89
- - **Long-running instances** carry continuity across an area of work. We plan, investigate and reason with instances of expertise souls that may remain useful across many tasks.
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
- An instance is not necessarily one ticket or one chat session. It can become deeply familiar with a situation over time. Lifetime follows the work: a short-lived instance can produce valuable learning, while a long-running instance does not automatically become a new soul.
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
- ### One soul can support many developers
74
+ ## Capabilities
94
75
 
95
- Several developers may each work with an instance of the same kernel-expert soul:
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
- - One investigates execution behaviour.
98
- - Another develops a capability integration.
99
- - Another supports an ongoing upgrade.
82
+ ## Why souls are valuable
100
83
 
101
- They share a specialisation, but not an active mind. Each develops an understanding of its assignment and keeps track of its own unfinished work. Accepted findings can become useful to other instances without making their working contexts identical.
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
- ## Core capabilities—and any others you need
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
- Three **core capabilities** provide the foundation for working as a team; a soul has at most one of each:
91
+ So:
106
92
 
107
- | Capability | What it provides |
108
- |---|---|
109
- | **Knowledge** | How agents consult knowledge, capture experience and retain useful learning. |
110
- | **Messaging** | How agents become reachable and communicate with people and other agents. |
111
- | **Tasks** | How work is assigned, tracked and coordinated. |
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
- These responsibilities are distinct. A conversation is not automatically a task record, and a task record is not automatically knowledge.
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
- Core capabilities are **not the only capabilities you can define**. Other capabilities can provide domain tools, specialised skills, research methods, review procedures or integrations with your systems.
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
- A **skill** teaches a way of working. A capability can supply that skill together with instructions, tools and supporting automation. OATS composes the selected resources into an instance’s working environment when it is created.
107
+ ## What OATS gives you
118
108
 
119
- ### Common contracts, different implementations
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
- The kernel supplies soul and instance identity, configuration, lifecycle, resource composition and exact, integrity-checked package locking. Models and harnesses remain user-selected execution choices; capabilities may declare requirements that a chosen setup must satisfy.
114
+ ## Work the way you choose
122
115
 
123
- Capabilities supply the behaviour behind their contracts:
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
- - A knowledge capability can choose its storage, reading strategy and learning workflow.
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
- A **package** distributes capabilities and their resources. Declaring one in a workspace is the decision to trust it; its capabilities reach a soul only when the soul or a workspace default selects them. Provider independence does not mean every combination is compatible; missing requirements must be reported, not silently discarded.
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
- ## Our approach to knowledge and learning
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
- The following is **our reference approach**, implemented through the official `oats.okf` knowledge capability. Other knowledge capabilities may adopt it, adapt it or use a different model.
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
- We distinguish four kinds of value:
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
- | Value | Where it belongs in our model |
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
- An experienced instance can have all four. We do not want to push them all into a permanent knowledge base.
173
+ A soul is a folder in one of those repositories:
146
174
 
147
- ### Save expertise, not a second description of the code
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
- > **Knowledge is what makes an expert an expert in a subject or project. It is not a description of what lives in the code.**
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
- Our promotion test asks:
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
- 1. Would an appropriate future instance act differently for knowing this?
154
- 2. Could it not have obtained this simply by reading the repository?
195
+ ### Working with your agents
155
196
 
156
- We preserve decisions and rationale, rejected alternatives, discoveries, research conclusions, design inspiration and maintained situational awareness. We do not duplicate code structure, file maps, ordinary task progress or information already implicit and quickly learnable from the repository.
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
- For example, **how to run a release** belongs in a skill. **Why installed-artifact verification is necessary** can be a lesson. **Which release check is still running** belongs in working state.
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
- Knowledge should improve judgment, not become a second source of increasingly stale project documentation.
207
+ ## Why we built it
161
208
 
162
- ## Our default: oats.okf
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
- `oats.okf` uses **Open Knowledge Format**: readable Markdown concepts with metadata, navigation and history.
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
- Our default model is **centralised and per soul**:
216
+ We believe:
167
217
 
168
- - A team selects a shared knowledge base.
169
- - Each adopted soul has a stable knowledge home.
170
- - Its instances consult accepted knowledge relevant to their work.
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 example, several UX-expert instances can contribute learning to the same knowledge home while retaining their own investigations and working state. Adopting a public soul does not implicitly send private learning back to its publisher.
222
+ ## For your own projects
175
223
 
176
- ### How learning flows
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
- 1. **Instances work and capture evidence.**
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
- Ordinary working instances do not directly rewrite the accepted knowledge base. For Git-backed knowledge, delivery uses pull requests; an open PR is not yet accepted knowledge. Plain-directory storage has its own publication mechanism. A delivery receipt is not proof of human approval or that another instance has read the result.
231
+ OATS is where the organisation defines, once, how its agents work.
184
232
 
185
- The current capability requires explicit bindings and provisioning. The default model is not a claim that every setup step is automatic.
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
- ## Knowledge and learning, your way
241
+ ## Schedules and triggers
188
242
 
189
- The approach above is our default, not a requirement. **You can set up your own knowledge procedures and ways of working and learning.** OATS provides the contracts and a default implementation; you can adapt existing capabilities or write your own.
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
- For example, you might want:
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
- - **New instances to inherit accumulated expertise.** A new kernel-expert instance begins with relevant decisions and lessons from earlier instances.
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
- Your knowledge capability determines what context an instance receives, how it builds on experience, and which learning is retained or shared. It can organise knowledge per soul, per topic or per project, centrally or alongside soul definitions, provided that it actually supports the chosen arrangement.
251
+ ## OATS Desktop
199
252
 
200
- The same principle applies to messaging and tasks: **OATS provides the contracts; you choose how your team works through them.**
253
+ A free agent development environment for macOS and Linux (x64) that puts a workspace in one window:
201
254
 
202
- ## Expertise can evolve
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
- Per-soul knowledge does not have to become a permanent silo. Souls can grow their scope, transfer knowledge to a more appropriate home, merge or split into more specialised souls.
261
+ It is optional: agents run, message each other and follow their schedules whether it is open or not.
205
262
 
206
- We call a deliberate split into new reusable specialisations **speciation**. An overall expert handling recurring UX work, for example, may provide evidence for a dedicated UX expert with its own skills and knowledge home. The overall expert can then consult that expertise rather than duplicate it.
263
+ ## Start here
207
264
 
208
- These are changes to propose and review—not changes agents make to themselves automatically. A busy period or a large collection of notes is not enough on its own.
265
+ **If you are a person,** your coding agent does the setup for you.
209
266
 
210
- See **[Knowledge, instances and evolving expertise](docs/knowledge-theory.md)** for the detailed explanation of:
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
- - Long-running instance expertise and working context.
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
- ## Getting started
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
- Begin with a small team and a real piece of work:
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
- 1. Choose compatible models and harnesses.
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
- On a machine with Node.js 22+, Git (2.45+ to fetch only what OATS reads; an older git fetches whole trees) and tmux, and a workspace repository to point at:
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
- npm install -g @awebai/oats
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
- [Start here](#start-here) does all of this for you. The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
284
+ Download it rather than web-fetching it: a summarising fetch would lose its exact commands.
238
285
 
239
- Further documentation:
286
+ ## Learn more
240
287
 
241
288
  - [Souls and instances](docs/souls-and-instances.md)
242
- - [Configuration](docs/configuration.md)
243
- - [Capabilities](docs/capabilities.md) and [layer contracts](docs/layers.md)
244
- - [Knowledge operations](docs/knowledge.md)
245
- - [Knowledge, instances and evolving expertise](docs/knowledge-theory.md)
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
- - [OATS TUI](docs/tui.md), the terminal client (`oats tui`, a preview)
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 and releases
296
+ ## Contributing
255
297
 
256
- Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS, or on a Linux user's systemd manager, can be run by hand on a hosted runner: see [named test runs](docs/named-test-runs.md).
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—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.
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 selected by a deployment may have their own licences and costs.
304
+ OATS is free and [MIT-licensed](LICENSE). Models and services a deployment chooses may have their own licences and costs.