# Conventions — canonical files and symlinks

OAS uses plain files so multiple harnesses can read the same agent. The rules
are small, but they matter. One canonical file or directory owns the content.
Compatibility paths are symlinks.

## Operating docs

`AGENTS.md` is canonical everywhere OAS manages an operating doc.

```text
soul/AGENTS.md          # canonical
soul/CLAUDE.md -> AGENTS.md
home/AGENTS.md -> soul/AGENTS.md
home/CLAUDE.md -> AGENTS.md
```

Write to `AGENTS.md`. Never create an independent `CLAUDE.md` under OAS
management. If you find one, treat it as a bug.

Injected blocks also live in `AGENTS.md`. Edit the source file named in the
block's marker, not the block itself. Reconciliation will overwrite direct
edits inside a marked block.

## Skills

`.agents/skills/` is canonical for skill directories.

```text
<level>/.agents/skills/      # canonical
<level>/.claude/skills -> ../.agents/skills
home/.agents/skills/         # linked skills for the instance
home/.claude/skills -> ../.agents/skills
```

A level's `.agents/skills/` is for hand-written laptop, workspace, or repo
skills. Integration skills do not copy into it. They attach at runtime from
the integration's own directory when the config resolves that layer.

For Claude Code, OAS symlinks the relevant skills into the instance home. pi
can discover them through the extension's resource discovery.

## Quick map

| Thing | Location |
|---|---|
| Config | `<level>/oas-config.yaml` |
| Level skills | `<level>/.agents/skills/` |
| Level Claude view | `<level>/.claude/skills` |
| Soul operating doc | `soul/AGENTS.md` |
| Soul Claude view | `soul/CLAUDE.md -> AGENTS.md` |
| Instance operating doc | `home/AGENTS.md -> soul/AGENTS.md` |
| Instance skills | `home/.agents/skills/` |
| Instance Claude skills | `home/.claude/skills -> ../.agents/skills` |

## Why symlinks

A copied compatibility file drifts. A symlink keeps one source of truth.

This costs some Windows friendliness and can confuse tools that do not expect
symlinks. OAS accepts that tradeoff because split operating docs are worse.
The kernel's own artifacts stay plain, git-versionable, and runtime-neutral.

## Discovery boundaries

pi discovers ancestor `.agents/skills` directories, but it stops at the git
repo root. That means a repo-nested session would normally miss workspace
skills above the repo.

OAS bridges that boundary for trusted projects. It contributes ancestor skill
directories above the repo root and links them into instance homes for Claude
Code. If a workspace skill is missing inside a repo, check this boundary
first.