# Implementation reference

This repo is the reference implementation of OAS, published as two npm
packages: **`@oas-framework/oas`** (the kernel + `oas` CLI + skills + injects
+ bundled integrations — install globally with `npm install -g`) and
**`@oas-framework/pi`** (a thin pi adapter installed with
`pi install npm:@oas-framework/pi` that locates the global kernel via the
`oas` binary, or `$OAS_PKG_ROOT`). The planned Claude plugin follows the same
adapter pattern — runtime packages ship only harness glue, never the kernel.

## Repository layout

| Path | Purpose |
|---|---|
| `lib/core.mjs` | The runtime-neutral OAS kernel (no pi imports). |
| `packages/pi/` | The pi adapter package (`@oas-framework/pi`): tools + `/agents` over the global kernel. |
| `bin/oas.mjs` | CLI: `doctor`, `install`, `use`, `init`, `sync`, `root`. |
| `skills/` | Kernel skills such as `oas`, `integration-authoring`, `oas-support`, `skill-craft`, `soul-craft`. |
| `integrations/` | Bundled layer integrations. |
| `injects/` | Kernel, work-mode, and workspace injection sources. |
| `docs/` | Public documentation. |
| `agents/` | This repo's own expert souls. |

## Agents root layout

The kernel finds the nearest `agents/` directory walking upward from the
current directory. `PI_AGENTS_ROOT` overrides the search.

```text
<workspace>/agents/
  <agent>/
    soul/
      soul.yaml
      AGENTS.md
      CLAUDE.md -> AGENTS.md
      skills/
      knowledge/          # if provided by the knowledge integration
    instances/
      <instance>/
        soul -> <agent>/soul
        AGENTS.md -> soul/AGENTS.md
        CLAUDE.md -> AGENTS.md
        .agents/skills/
        .claude/skills -> ../.agents/skills
        work/
        TASK.md
        instance.json
        STATE.md log.md notes/   # if provided by the knowledge integration
  local-agents/
    <name>/...             # uncommitted local agents
```

Legacy `tmp-agents/` roots are still read for compatibility.

## Registered tools

| Tool | Purpose |
|---|---|
| `agents_status` | List the closest agents root, known souls, running instances, importable defs, and enabled models. |
| `spawn_agent` | Spawn an existing soul, create a local agent from instructions, or import an agent definition. |
| `create_agent` | Create a persistent soul without spawning an instance. |
| `retire_agent` | Retire another instance. It refuses to retire the caller. |
| `retire_self` | Retire the calling instance safely, with delayed window kill. Registered only inside spawned instances. |

The `/agents` interactive command wraps the same operations in the pi UI.

## CLI

`bin/oas.mjs` installs as `oas`.

```bash
oas doctor [dir]                    # resolved config, origins, hooks, skills, requirements
oas use <integration> --for <layer> # bind an integration at this level
oas use none --for <layer>          # disable a layer at this level
oas init [--raw]                    # create oas-config.yaml
oas sync                            # reconcile injections into every soul
```

`oas use` detects the level from the target directory: home is laptop, a git
repo root is repo, anything else is workspace. It edits `oas-config.yaml`,
prints the resolved check, and warns about missing requirements.

## Injections

`applyInjections` writes marker-guarded blocks into a soul's `AGENTS.md`.
It runs when a soul is created and before spawn, and `oas sync` can run it
for every soul under an agents root.

The wanted blocks are, in order:

1. Kernel OAS injection (`injects/oas.md` by default, configurable with
   `oas.agents-md-injection`).
2. Work-mode injection (`injects/work-worktree.md` or `injects/work-checkout.md`,
   configurable under `work-modes`).
3. One injection per resolved layer integration.
4. Unconditional injections from the config's top-level `agents-md-injection:` map.

Blocks record their source path. Edit the source, not the block.

## Kernel skills

Kernel skills are discovered only in OAS contexts: instance homes, dirs whose
config chain has a below-laptop config, or agents roots that contain souls.
Random directories on the machine do not get OAS skills.

The main kernel skills are:

- `oas` — operating inside OAS, lifecycle, roster, self-retirement, doctor.
- `integration-authoring` — route custom integration work to the
  integrations-expert soul.
- `oas-support` — route deep framework questions to the oas-expert soul.
- `skill-craft` and `soul-craft` — authoring skills and souls.

## Lifecycle hooks

The kernel runs integration hooks for resolved layers. Supported events:

| Event | When |
|---|---|
| `soul-scaffold` | A soul is created or lazily migrated. |
| `spawn` | An instance home has been prepared. |
| `post-commit` | A spawned instance successfully ran `git commit` through the bash tool. |
| `retire` | Before the instance home is removed. |

Hooks run with `OAS_EVENT`, `OAS_INSTANCE`, `OAS_HOME`, `OAS_AGENT`,
`OAS_SOUL`, `OAS_CONTEXT`, `OAS_WORKSPACE`, `OAS_ROOT`, `OAS_LEVEL`,
`OAS_SETTINGS`, and `OAS_META` where relevant. Hook output may include JSON
`{ meta, brief, warning }`. Failures warn and never block spawn.

## Default integrations

### oas-okf

Provides the knowledge layer. It scaffolds the soul OKF bundle, creates
instance memory files, and uses the `post-commit` event for continuous
harvest. A memory-harvest instance attaches to the committer's work tree,
promotes or drops pending notes, commits a `memory-harvest:` change, deletes
processed notes, and retires itself.

Retirement is a knowledge no-op.

### oas-aweb

Provides the messaging layer. It mints a team-scoped aweb identity at spawn
and self-deletes it at retire. Missing `aw`, missing `.aw` roots, or mint
failures warn but do not block the instance.

## Compatibility

Legacy `.agents/workspace.yaml` configs are read when no modern
`oas-config.yaml` exists at that level. The shim maps old keys to the current
shape, including `agents-md-append`, `skills`, `knowledge-sections`, and
legacy aweb settings.

## Planned

- Separately installable integration packages.
- A dashboard over agents, instances, tasks, and knowledge depth.
- Layout adapters for non-default agents-root shapes.