OAS — Open Agent Specialization

Agents should grow into experts, not restart as generalists every time.

Most agent setups give a repo one assistant. One AGENTS.md, one skill set, one memory story. Harnesses like Claude Code add subagents on top, but those are second-class — throwaway calls inside someone else's session that you cannot open, steer, or let learn.

OAS treats agents as specialized experts, and every one is a first-class citizen. The UI agent, backend expert, maintainer, and review agent each get their own setup, their own memory, and their own full session that you can walk into and steer.

The problems OAS solves

Agents forget. Every new session starts from zero. OAS gives each expert a durable soul that accumulates knowledge and skills. Instances capture what they learn, and a harvest process promotes the durable lessons back into the soul. The tenth incarnation of your backend expert knows things the first one had to figure out.

Subagents are second-class. In most harnesses, a subagent is a hidden tool call. In OAS, every spawned agent is a full pi or Claude Code session in its own tmux window. You can attach to any of them and steer. And every instantiation is an instantiation of a soul, so everything it learns nourishes that soul.

Workflows are rigid. OAS agents are all peers that launch through tmux and can talk to each other, so workflows can be as simple or as complex as the work needs. A task can span several repos, each with a coordinator soul instantiated to run the cross-repo work and that repo's own developers. Those developers might be a backend and a frontend expert, and the backend expert can launch helper instances of itself for parallel work. A shape that works well in practice: one coordinator, two developers, a reviewer or two on a different model, and a maintainer gating main on yet another model.

One size never fits all teams. Knowledge, messaging, and task tracking are pluggable layers. One workspace runs OKF, aweb, and Jira. Another runs a team wiki, Slack, and GitHub Issues. A solitary repo turns messaging off. Only the layer binding changes, never what a soul is.

Souls, instances, sessions

A soul is the durable expert. It is committed and reviewed like code:

• soul.yaml — name, target repo, work mode, runtime, and default model.
• AGENTS.md — the canonical operating doc (CLAUDE.md is a compatibility view).
• skills/ — procedures this expert knows how to run.
• knowledge/ — long-term memory, if a knowledge integration provides one.

The soul is model-agnostic as an artifact. Its default model is only a default, and an instance can be spawned or resumed on a different model.

When work starts, the soul is instantiated as an instance. An instance is a named incarnation with its own ID, home, worktree (if needed), briefing, and lifecycle. Starting a session inside that instance brings it to life. The session is a full coding-agent session with its own tools and home, not a lightweight subagent call. One instance can hold several sessions across restarts, compactions, and model switches until it is retired.

A vampire analogy helps:

• Pepe's soul is what makes all Pepes Pepe.
• An instance gives Pepe's soul a unique body — call it Pepe 1 — that can come to life.
• A session brings Pepe 1, body and soul, into the world.
• Pepe 1 lives, interacts with the world, works, and learns. What he learns nourishes the soul.
• Maybe Pepe 1 even dies and resuscitates a couple times: the session stops, then another session starts in the same instance.
• Finally, Pepe 1's body is cremated. He is a vampire, so that body can never come back to life — the instance has been retired.
• But it is fine. Future incarnations of Pepe benefit from Pepe 1's experience. Pepe's soul can reincarnate in another body, and new Pepes carry the useful learnings and teachings forward.

Souls compound. Instances do the work. A soul can have as many instances as people need. Instances are runtime state and normally gitignored, so expert souls can travel with a repo while different teams instantiate them into their own local agent teams without colliding.

agents/docs-expert/soul/              # the durable expert
agents/docs-expert/instances/audit/   # one disposable incarnation

OAS experts also work as a team. One agent can spawn another, and the recommended messaging layer is aweb.ai: it gives each instance an identity so agents can coordinate with each other and with you. A task layer can bind the team to Jira, Linear, GitHub Issues, or anything else.

The kernel artifacts are plain files: markdown, YAML, and symlinks. Any harness can read them.

Read Souls and instances for the full anatomy and lifecycle.

The five layers

OAS is built around five layers. The kernel owns the layers that make an agent a soul and its instances. The other layers are contracts that integrations bind to real tools.

#	Layer	What it provides	Solved by
1	Soul	Durable expert identity: AGENTS.md, soul skills, long-term knowledge	OAS kernel
2	Knowledge	Where learning lives, how it is captured, and how it gets promoted — the format is pluggable, but we believe some ideas hold regardless: see knowledge theory	Integration, default oas-okf
3	Instances	Where a soul is instantiated, gets a unique ID and home, and interacts with the world	OAS kernel
4	Messaging	Reachable identities so agents and humans can talk	Integration, default oas-aweb
5	Tasks	Work queues and status that outlive any one instance	Integration, no shipped default

This split is what makes OAS flexible. The kernel does not prescribe how to solve the pluggable fundamental layers — knowledge, messaging, and tasks. Those layers are tackled by integrations, and you can tackle them any way you want.

See The five layers for the full model.

Work modes

A work mode decides what an instance's ./work points at and what discipline the agent must follow. It is part of a soul's identity.

• worktree — work/ is a git worktree on the instance's own branch. Use it for agents that edit code or docs independently. Several developer instances can work in parallel without stepping on each other.
• checkout — work/ is a symlink to the repo checkout itself, on the currently checked-out branch. Use it for coordinators, maintainers, and auditors that work on the repo's current state.
• attached — a spawn-time mode for service agents that operate inside another instance's tree, such as the memory harvester.

Retirement

An instance ends when it is retired. Retirement runs the integration retire hooks (for example, aweb deletes the instance's messaging identity), removes the instance home, and removes the instance's worktree if it had one. An agent can retire itself with retire_self when its briefing says it is done. Retirement is irreversible for that body, but the soul carries the learnings forward.

The knowledge lifecycle

With the default oas-okf integration, learning flows in a loop.

1. Spawn. The instance gets episodic memory files: STATE.md (live working state), log.md (dated milestones), and notes/ (captured insights).
2. Work. As the instance works, it keeps STATE.md current and writes non-obvious insights into notes/ as small OKF concepts. A fresh session can resume the instance from these files alone.
3. Harvest. Every successful git commit fires a lifecycle event. If the instance has pending notes, a memory-harvest agent spawns attached to the same work tree. It promotes durable lessons into the soul's knowledge bundle or soul skills, merges or drops the rest, commits, and retires itself.
4. Compound. The next instance of that soul starts with everything past incarnations learned.

Harvest happens continuously after commits, so long-lived instances feed their souls while still alive. Retirement is a knowledge no-op. See Knowledge and knowledge theory.

Workspaces: where configuration lives

An OAS workspace is any scope where agents share configuration. It can be your laptop, a folder of related repos, or a single repo. The workspace root is where you put oas-config.yaml.

~/oas-config.yaml                         # laptop-wide OAS workspace
~/acme/oas-config.yaml                    # multi-repo OAS workspace
~/acme/project-service/oas-config.yaml    # repo OAS workspace

The rule for placing a setting is simple. Put it at the level where every agent below should feel it. In multi-repo work, a decision that affects all agents across the repos — the task tracker, the messaging setup, shared conventions — goes in the config at the root folder that contains them. A decision only one repo cares about goes in that repo's config.

The config answers the questions that make a workspace feel local. Which knowledge system, messaging tool, and task tracker should agents use, and which skills teach those workflows. What all agents here should know before they start. How a fresh worktree gets prepared.

Resolution walks upward from where the agent works, and each layer resolves independently.

• The nearest workspace wins for the setting it declares. Missing settings inherit from outer workspaces. none turns a setting off.
• A single agent can mix origins. Knowledge from its repo workspace, tasks from the multi-repo workspace, messaging from the laptop.
• The CLI makes it visible. oas use <integration> --for <layer> writes a binding. oas doctor shows the resolved chain and where each setting came from.

So your laptop can default everything to OKF, aweb, and Linear. A multi-repo workspace such as ~/acme can override only tasks with Jira. One repo inside it can bring its own knowledge integration while inheriting the rest. See the worked configuration examples.

Injections: teach every soul at once

An injection is a marker-guarded instruction block that OAS writes into a soul's AGENTS.md. One file at the workspace root becomes part of the operating doc of every soul below it. Change the file, run oas sync, and every soul in the workspace is reconciled — no hand-editing.

Injections come from four sources, composed in order:

1. Kernel — tells agents they run on OAS and which skills explain it.
2. Work mode — the worktree or checkout discipline for using ./work.
3. Integrations — how to work with the resolved knowledge, messaging, and task layers.
4. Workspace — your own conventions, for every soul under the config.

Each source can use the shipped default, point at your own file, or be disabled with none. Every injected block carries a marker naming its source file, so you always know where a rule came from. Edit the source, never the block.

Planned: injections per agent type. Define a family of developer souls and inject a block into every soul of that family — coding standards for all developers, checklists for all reviewers — without touching coordinator or maintainer souls.

See Configuration for the full model.

Integrations tackle the pluggable layers

Knowledge, messaging, and tasks are pluggable. An integration is how a workspace solves one of them. It binds a layer to a framework and makes that framework usable by agents.

An integration is usually small. It has skills that teach agents how to use the framework, a default injection that tells souls those skills exist, and optional hooks for lifecycle work such as minting an identity or harvesting memory after a commit. The smallest hand-rolled integration needs no package and no manifest — a skills directory, an injection file, and a config entry are enough.

This repo also ships an integrations-expert soul that can help design and build one with you. See Integrations for examples and manifest details.

What ships

The reference implementation ships in this repo as a pi package:

• extension/ — the OAS kernel and pi tools.
• bin/oas.mjs — oas doctor, oas use, oas init, oas sync.
• skills/ — kernel skills such as oas, soul-craft, and integration-authoring.
• integrations/oas-okf/ — the default knowledge layer.
• integrations/oas-aweb/ — the default messaging layer.
• injects/ — kernel, work-mode, and workspace injections.

Use oas init for default OKF + aweb config, or oas init --raw for all layers set to none.

Status as of 2026-07-09: the config cascade, layer resolution, injections, oas CLI, local agents, lifecycle hooks, continuous post-commit harvest, and legacy .agents/workspace.yaml shim are implemented. Planned next: per-agent-type injections, separately installable integration packages, dashboard, and layout adapters.

See Implementation for details.

Installation

The oas CLI installs globally from npm:

npm install -g @oas-framework/oas
oas doctor          # see the resolved config from anywhere

For pi users, install the adapter package to get the agent tools (spawn_agent, agents_status, retire_agent, /agents) and skill discovery — it is a thin adapter over the globally installed CLI:

pi install npm:@oas-framework/pi

The recommended onboarding path is to clone the framework repo, then ask an agent with the OAS package tools to instantiate oas-expert from this repo and help you set up OAS.

git clone https://github.com/josep-reyero/oas-framework.git
cd oas-framework
pi install .

Then start or reload a pi session so the package tools are available. From an agent that can use those tools, ask something like:

Spawn the oas-expert agent in the oas-framework repo and ask it to help me set up OAS for my workspace.

The oas-expert soul lives at agents/oas-expert/. It knows the framework, the config model, and the setup path. Talk to it, describe the workspace you want OAS to govern, and let it guide the first config and agent setup.

If you already know what you want, you can also create config directly:

oas init          # default okf + aweb setup
oas init --raw    # no integrations; wire your own

Learn more

• The five layers — the specialization model.
• Souls and instances — durable experts and disposable runs.
• Knowledge — capture, harvest, and promotion.
• Knowledge theory — what belongs in a soul vs an instance, whatever the format.
• Configuration — workspaces, resolution, injections, and examples.
• Integrations — writing and shipping layer bindings.
• Conventions — canonical files, symlinks, and skill paths.

Origins

OAS grew out of the a2am team architecture and the LFX engineering vision for agent-native engineering. It builds on open standards: agents.md for operating docs, Agent Skills for procedures, and OKF for the default knowledge bundle.