@ai-outfitter/outfitter 1.1.2 → 1.3.0

package/docs/documentation/agents.md

@@ -1,6 +1,11 @@
 # Agents
 
-An agent is the protocol's identity resource — and, in Outfitter, the thing you run. A directory under `agents/<id>/` holds an `agent.md` definition and an optional `config.json`. Together they carry both _who the agent is_ and _what it runs with_: its skills, MCP servers, subagents, extensions, plugins, model, thinking level, and tool policy. That whole bundle — identity plus loadout — is what earlier drafts called a "profile." There is no separate profile resource; **an agent is the profile**. See [Profiles](./profiles.md).
+An agent is the protocol's identity resource — and, in Outfitter, the thing you run.
+A directory under `agents/<id>/` holds an `agent.md` definition and an optional `config.json`.
+Together they carry both _who the agent is_ and _what it runs with_: its skills, MCP servers, subagents, extensions, plugins, model, thinking level, and tool policy.
+That whole bundle — identity plus loadout — is what earlier drafts called a "profile."
+There is no separate profile resource; **an agent is the profile**.
+See [Profiles](./profiles.md).
 
 ```text
 .agents/
@@ -33,6 +38,8 @@ model: gpt-5.2
 thinking: high
 tools:
   allow: [read, edit, bash]
+append_system_prompt:
+  - repo_file: docs/architecture.md
 ---
 
 # Engineer
@@ -40,11 +47,12 @@ tools:
 You implement changes directly, keep diffs small, and verify before claiming done...
 ```
 
-`name` is the stable slug used for resolution. The optional `label` is the human-readable profile
-name shown during setup and in interactive harness UI. When `label` is omitted, Outfitter uses the
-first level-one Markdown heading, then falls back to the slug.
+`name` is the stable slug used for resolution.
+The optional `label` is the human-readable profile name shown during setup and in interactive harness UI.
+When `label` is omitted, Outfitter uses the first level-one Markdown heading, then falls back to the slug.
 
-Keep the prose focused on durable identity and behavior. Per-capability procedures belong in [skills](./skills.md); the frontmatter only _selects_ resources by slug — it never copies their content.
+Keep the prose focused on durable identity and behavior.
+Per-capability procedures belong in [skills](./skills.md); the frontmatter only _selects_ resources by slug — it never copies their content.
 
 ### Loadout fields
 
@@ -59,13 +67,59 @@ Keep the prose focused on durable identity and behavior. Per-capability procedur
 | `thinking`   | Thinking/effort level.                                                       |
 | `tools`      | Allowed/denied tool policy for the run.                                      |
 
-Every value is a slug resolved across layers. Skills first check `agents/<agent>/skills/<slug>/` across layer precedence, then fall back to catalog-wide `skills/<slug>/`. This lets an agent own private implementation capabilities without exposing them to every agent in the catalog. See [Skills](./skills.md#agent-local-skills).
+Every value is a slug resolved across layers.
+Skills first check `agents/<agent>/skills/<slug>/` across layer precedence, then fall back to catalog-wide `skills/<slug>/`.
+This lets an agent own private implementation capabilities without exposing them to every agent in the catalog.
+See [Skills](./skills.md#agent-local-skills).
 
-`knowledge` and `commands` resolve the same way — an agent may keep private files under `agents/<agent>/knowledge/` and `agents/<agent>/commands/`, local-first over the catalog-wide trees. `subagents` are always catalog-wide (a delegate is a shared agent). `extensions`/`plugins` are harness-native passthroughs with no on-disk namespace, and `model`/`thinking`/`tools` are per-agent already via `config.json` merge.
+`knowledge` and `commands` resolve the same way — an agent may keep private files under `agents/<agent>/knowledge/` and `agents/<agent>/commands/`, local-first over the catalog-wide trees.
+`subagents` are always catalog-wide (a delegate is a shared agent).
+`extensions`/`plugins` are harness-native passthroughs with no on-disk namespace, and `model`/`thinking`/`tools` are per-agent already via `config.json` merge.
+
+## Inheritance and prompt fragments
+
+An agent may specialize one or more base agents with `inherits`.
+Parents compose recursively, parent-first, and multiple parents keep the order written in the child.
+Diamond graphs include each ancestor once.
+Outfitter fails validation and composition for missing parents, self-inheritance, or indirect cycles.
+
+```markdown
+---
+name: platform-engineer
+inherits: engineer
+skills: [nix, kubernetes]
+system_prompt:
+  file: prompts/platform-system.md
+append_system_prompt:
+  - file: prompts/platform-review.md
+  - repo_file: docs/architecture.md
+prompt_template:
+  file: prompt-templates/implementation.md
+---
+
+# Platform Engineer
+
+You specialize the base engineer for NixOS and Kubernetes work.
+```
+
+Merge policy is deterministic: Markdown bodies append ancestor-first and child-last; list fields (`skills`, `subagents`, `mcp`, `extensions`, `plugins`, `append_system_prompt`) de-duplicate parent-first; scalar controls (`system_prompt`, `prompt_template`, `model`, `thinking`, `label`, `description`) use the nearest child declaration.
+Parent-declared skills resolve against that parent's local skill namespace before catalog fallback, so a child cannot accidentally capture a parent's private loadout.
+
+Prompt sources are explicit objects.
+`file` reads trusted catalog content relative to the `.agents` layer that owns the declaring agent and must stay inside that layer.
+`repo_file` reads active-repository content relative to the project root, remains contained after symlink resolution, and is treated as untrusted repository context; missing optional repository files warn so reusable catalog agents do not become brittle across projects.
+Named prompt slugs are intentionally not accepted yet.
+
+Effective prompt order is: selected `system_prompt` or root `system-prompt.md`; root `agents.md`; inherited then child `append_system_prompt`; inherited then child agent bodies; any runtime passthrough append prompts.
+
+Inheritance is not delegation.
+Inheritance composes one selected agent's identity and loadout before launch.
+`subagents` expose other agents as delegates the selected agent may call at runtime.
 
 ## Pi configuration overlay
 
-An agent may own native Pi configuration under `agents/<agent>/pi/`. Outfitter overlays that folder into the temporary `PI_CODING_AGENT_DIR` before launching Pi, so native files keep their standard names and formats:
+An agent may own native Pi configuration under `agents/<agent>/pi/`.
+Outfitter overlays that folder into the temporary `PI_CODING_AGENT_DIR` before launching Pi, so native files keep their standard names and formats:
 
 ```text
 agents/founder/
@@ -77,26 +131,24 @@ agents/founder/
     └── themes/
 ```
 
-The overlay is file-based. Source layers are applied from lowest to highest precedence, so a workspace `agents/founder/pi/keybindings.json` replaces the same file from a global or remote catalog while unrelated lower-layer files remain present. Outfitter does not follow symlinks from the overlay. The folder is ignored when the selected harness is not Pi.
+The overlay is file-based.
+Source layers are applied from lowest to highest precedence, so a workspace `agents/founder/pi/keybindings.json` replaces the same file from a global or remote catalog while unrelated lower-layer files remain present.
+Outfitter does not follow symlinks from the overlay.
+The folder is ignored when the selected harness is not Pi.
 
-Outfitter writes generated identity, composed skills, selected delegates, and
-selected MCP servers after applying the native overlay, and seeds durable Pi
-credentials immediately before launch. Those runtime-owned resources therefore
-cannot be replaced accidentally by a profile overlay.
+Outfitter writes generated identity, composed skills, selected delegates, and selected MCP servers after applying the native overlay, and seeds durable Pi credentials immediately before launch.
+Those runtime-owned resources therefore cannot be replaced accidentally by a profile overlay.
 
-`agents/<agent>/mcp.json` merges by server id over layered tree-root `mcp.json`
-files. The Pi projection writes only the servers selected by the active
-agent's `mcp` loadout into the runtime `mcp.json`.
+`agents/<agent>/mcp.json` merges by server id over layered tree-root `mcp.json` files.
+The Pi projection writes only the servers selected by the active agent's `mcp` loadout into the runtime `mcp.json`.
 
-The per-agent `agents/<agent>/hooks/` namespace remains reserved and is not yet
-projected (adapter parity is tracked in
-[#183](https://github.com/ai-outfitter/outfitter/issues/183)). Its presence
-surfaces a validation warning so content placed there is never silently
-dropped.
+The per-agent `agents/<agent>/hooks/` namespace remains reserved and is not yet projected (adapter parity is tracked in [#183](https://github.com/ai-outfitter/outfitter/issues/183)).
+Its presence surfaces a validation warning so content placed there is never silently dropped.
 
 ## config.json
 
-The optional `config.json` carries structured or harness-specific configuration that is awkward in frontmatter, following the protocol's schema for the pinned revision. JSON files merge across layers per the protocol's JSON merge behavior, so a workspace layer can adjust one field of a globally defined agent — swap the model, add an extension — without copying the whole definition.
+The optional `config.json` carries structured or harness-specific configuration that is awkward in frontmatter, following the protocol's schema for the pinned revision.
+JSON files merge across layers per the protocol's JSON merge behavior, so a workspace layer can adjust one field of a globally defined agent — swap the model, add an extension — without copying the whole definition.
 
 ## Tree-level context
 
@@ -118,10 +170,13 @@ outfitter run engineer --harness claude
 
 ## Resolution
 
-Agents resolve by slug across layers — workspace, global, then remote sources — with merge-by-ID semantics: a workspace `agents/engineer/` overrides a global or remote one. Agent-local skills merge by their owner and slug using the same layer order. `outfitter list agents` shows every resolvable agent and its winning source; `outfitter list skills --agent engineer` shows its effective skill namespace; `outfitter validate` reports broken loadout slugs and shadowed definitions.
+Agents resolve by slug across layers — workspace, global, then remote sources — with merge-by-ID semantics: a workspace `agents/engineer/` overrides a global or remote one.
+Agent-local skills merge by their owner and slug using the same layer order.
+`outfitter list agents` shows every resolvable agent and its winning source; `outfitter list skills --agent engineer` shows its effective skill namespace; `outfitter validate` reports broken loadout slugs and shadowed definitions.
 
 ## Agents as delegates
 
-The same agent definition can also be selected as a [subagent](./subagents.md) in another agent's `subagents` list — a delegate the run can hand focused work to. A leader agent's loadout is where that delegation is declared.
-For Pi runs, Outfitter also resolves and materializes the delegate's selected skills. Those skills
-are available to the delegate without being loaded into the leader's active skill set.
+The same agent definition can also be selected as a [subagent](./subagents.md) in another agent's `subagents` list — a delegate the run can hand focused work to.
+A leader agent's loadout is where that delegation is declared.
+For Pi runs, Outfitter also resolves and materializes the delegate's selected skills.
+Those skills are available to the delegate without being loaded into the leader's active skill set.

package/docs/documentation/migration.md

@@ -1,18 +1,21 @@
 # Migration from legacy profiles
 
-Earlier Outfitter versions used an authored profile system: `.outfitter/` directories, `profile.yml` files, profile inheritance, and `--profile` pointing at profile definitions. [RFC #165](https://github.com/ai-outfitter/outfitter/issues/165) replaces that system with the Dotagents `.agents` protocol as a hard cut: the end-state runtime has **no knowledge of the old format** — no compatibility reader, no migration command, no deprecated aliases. (These docs describe that target; the released CLI still runs the legacy profile format during the transition.) This page is the manual migration reference, and the bundled Outfitter skill can walk an agent session through it interactively.
+Earlier Outfitter versions used an authored profile system: `.outfitter/` directories, `profile.yml` files, profile inheritance, and `--profile` pointing at profile definitions.
+[RFC #165](https://github.com/ai-outfitter/outfitter/issues/165) replaces that system with the Dotagents `.agents` protocol as a hard cut: the end-state runtime has **no knowledge of the old format** — no compatibility reader, no migration command, no deprecated aliases.
+(These docs describe that target; the released CLI still runs the legacy profile format during the transition.)
+This page is the manual migration reference, and the bundled Outfitter skill can walk an agent session through it interactively.
 
 ## Mapping
 
 | Legacy                                                  | End state                                                                                                                                                                                        |
 | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `.outfitter/profiles/<id>/profile.yml` (or `<id>.yml`)  | Split into resources: identity → `agents/<id>/agent.md`, procedures → `skills/`; the loadout lives in that [agent](./profiles.md)'s frontmatter / `config.json` — there is no separate selection |
-| `controls.system_prompt` / `append_system_prompt`       | `system-prompt.md`, `agents.md`, and the agent's `agent.md` body                                                                                                                                 |
+| `controls.system_prompt` / `append_system_prompt`       | Agent frontmatter `system_prompt` / `append_system_prompt` with explicit `{ file }` or `{ repo_file }` sources; use root `system-prompt.md` / `agents.md` for tree-wide context                  |
 | `controls.model`, `provider`, `thinking`                | `models.json` (and per-agent `config.json`)                                                                                                                                                      |
 | `controls.skills`                                       | The agent's `skills:` loadout; skills live at `skills/<id>/`                                                                                                                                     |
 | `controls.extensions`, `args`, `environment`            | Harness configuration projected by adapters; MCP servers → `mcp.json`                                                                                                                            |
-| Profile inheritance (`inherits:`)                       | Layer merge-by-ID, plus shared context in `system-prompt.md` / `agents.md`                                                                                                                       |
-| `template: true` base profiles                          | A base agent whose shared context lives in `system-prompt.md` / `agents.md` (or a base agent selected as a delegate)                                                                             |
+| Profile inheritance (`inherits:`)                       | Agent frontmatter `inherits:` naming one parent slug or an ordered parent list; manually translate the old profile into an agent first                                                           |
+| `template: true` base profiles                          | A base agent referenced with agent `inherits`; there is no separate template flag                                                                                                                |
 | `~/.outfitter/settings.yml`                             | `~/.agents/settings.yml`                                                                                                                                                                         |
 | `<project>/.outfitter/settings.yml`                     | `<project>/.agents/settings.yml`                                                                                                                                                                 |
 | `<project>/.outfitter/local/settings.yml` (nested dir)  | `<project>/.agents/settings.local.yml` (flat, gitignored)                                                                                                                                        |
@@ -25,14 +28,20 @@ Earlier Outfitter versions used an authored profile system: `.outfitter/` direct
 
 ## Procedure
 
-1. **Inventory** your `.outfitter/profiles`. For each profile, separate what it contains: identity/policy prose, capability procedures, model/provider config, tool wiring.
-2. **Create resources**: one `agents/<id>/agent.md` per durable identity; one `skills/<id>/` per capability (most `append_system_prompt` procedure text belongs in skills); shared context into `agents.md`; model config into `models.json`; MCP into `mcp.json`.
-3. **Rebuild as agents**: for each profile people actually ran, create an `agents/<id>/agent.md` whose frontmatter (or `config.json`) loadout selects the new resources by slug. Set `default_agent` to the one you run most. Inheritance chains become shared context in `system-prompt.md` / `agents.md` (or a base agent selected as a delegate), not an ordered selection.
-4. **Move settings**: relocate `~/.outfitter/settings.yml` content into `~/.agents/settings.yml`, project settings into `<project>/.agents/settings.yml`, and anything under `.outfitter/local/` into a flat `.agents/settings.local.yml` (gitignore it). Rename `profile_sources` to `sources`; sources must now publish `.agents` payloads.
+1. **Inventory** your `.outfitter/profiles`.
+   For each profile, separate what it contains: identity/policy prose, capability procedures, model/provider config, tool wiring.
+2. **Create resources**: one `agents/<id>/agent.md` per durable identity; one `skills/<id>/` per capability; shared context into `agents.md`; model config into `models.json`; MCP into `mcp.json`.
+   Move prompt fragments that must load eagerly into catalog-contained `file` sources or project-contained `repo_file` sources.
+3. **Rebuild as agents**: for each profile people actually ran, create an `agents/<id>/agent.md` whose frontmatter (or `config.json`) loadout selects the new resources by slug.
+   Translate reusable base profiles into base agents and preserve intentional inheritance order with agent `inherits`.
+   Set `default_agent` to the one you run most.
+4. **Move settings**: relocate `~/.outfitter/settings.yml` content into `~/.agents/settings.yml`, project settings into `<project>/.agents/settings.yml`, and anything under `.outfitter/local/` into a flat `.agents/settings.local.yml` (gitignore it).
+   Rename `profile_sources` to `sources`; sources must now publish `.agents` payloads.
 5. **Validate**: `outfitter validate --strict`, then `outfitter dump` and review the tree.
 6. **Delete** the `.outfitter/` directory once the dump matches expectations.
 
-A remote repository _named_ `.outfitter` remains a supported convention for organization control repos — but only when it publishes the new protocol payload. The name is supported; the previous profile layout inside it is not.
+A remote repository _named_ `.outfitter` remains a supported convention for organization control repos — but only when it publishes the new protocol payload.
+The name is supported; the previous profile layout inside it is not.
 
 ## Claude Code users
 

package/docs/documentation/profiles.md

@@ -1,30 +1,47 @@
 # Agent profiles
 
-"Profile" is a description, not a resource or a settings key. There is no `profile.yml`, no `profiles:` map, and no profile file format. What earlier drafts modeled as a standalone profile — a named selection of skills, subagents, model, and so on — is now just an [agent](./agents.md) and its loadout.
+"Profile" is a description, not a resource or a settings key.
+There is no `profile.yml`, no `profiles:` map, and no profile file format.
+What earlier drafts modeled as a standalone profile — a named selection of skills, subagents, model, and so on — is now just an [agent](./agents.md) and its loadout.
 
 ## Profiles are agents
 
-An **agent profile** is the whole bundle an agent carries: its identity (`agent.md`) plus the loadout declared in that agent's frontmatter or `config.json` — skills, MCP servers, subagents, extensions, plugins, model, thinking level, and tool policy. When someone says "the engineer profile," they mean the `engineer` agent with everything it composes.
+An **agent profile** is the whole bundle an agent carries: its identity (`agent.md`) plus the loadout declared in that agent's frontmatter or `config.json` — skills, MCP servers, subagents, extensions, plugins, model, thinking level, and tool policy.
+When someone says "the engineer profile," they mean the `engineer` agent with everything it composes.
 
-Folding profiles into agents removes a layer of indirection. Instead of a settings map that points at resources that point at an identity, one agent directory holds identity and loadout together, resolves by slug like any other resource, and is what you run:
+Folding profiles into agents removes a layer of indirection.
+Instead of a settings map that points at resources that point at an identity, one agent directory holds identity and loadout together, resolves by slug like any other resource, and is what you run:
 
 ```bash
 outfitter run engineer
 outfitter run engineer --harness claude
 ```
 
-`outfitter list agents` shows every resolvable agent and where each resolves from, including shadowed IDs. Set `default_agent` in [settings](./settings.md) to choose what plain `outfitter` runs.
+`outfitter list agents` shows every resolvable agent and where each resolves from, including shadowed IDs.
+Set `default_agent` in [settings](./settings.md) to choose what plain `outfitter` runs.
 
 ## Where the loadout lives
 
-The loadout lives on the agent, not in settings. Add or change what an agent composes by editing that agent's `agents/<id>/agent.md` frontmatter or `config.json` — see [Agents](./agents.md#loadout-fields) for the field list. To override just one field from a higher layer (swap the model, add an extension) without redefining the agent, put it in the agent's `config.json`: JSON files shallow-merge by key across layers. An `agent.md` resolves whole-resource by ID — the winning layer's `agent.md` replaces lower ones rather than field-merging — so a partial `agent.md` would discard the base identity.
+The loadout lives on the agent, not in settings.
+Add or change what an agent composes by editing that agent's `agents/<id>/agent.md` frontmatter or `config.json` — see [Agents](./agents.md#loadout-fields) for the field list.
+To override just one field from a higher layer (swap the model, add an extension) without redefining the agent, put it in the agent's `config.json`: JSON files shallow-merge by key across layers.
+An `agent.md` resolves whole-resource by ID — the winning layer's `agent.md` replaces lower ones rather than field-merging — so a partial `agent.md` would discard the base identity.
 
 Settings ([settings.md](./settings.md)) is left with just resolution and launch concerns — `default_agent`, `default_harness`, `sources`, and state policy — not resource selection.
 
 ## Composing from a base
 
-To share behavior across several agents, keep shared operating context in the tree's `system-prompt.md` and `agents.md` — every agent in the tree inherits those — and put shared procedures in [skills](./skills.md) each agent selects. Selecting an agent as a subagent does _not_ share its policy; it only makes that agent available as a delegation target. The [persona](./personas.md) convention builds on the shared-context idea: one shared review agent, many single-file persona documents appended at launch.
+Use `inherits` when one agent is a specialization of another.
+The base agent's body and additive loadout compose first; child bodies append, child scalar controls override, and inherited parent-local resources retain their parent ownership.
+For example, `platform-engineer` can `inherits: engineer` and add `skills: [nix, kubernetes]`.
+Multiple parents are ordered left-to-right, recursively, with diamond ancestors included once.
+
+Use tree-level `system-prompt.md` and `agents.md` for context shared by every agent, and [skills](./skills.md) for reusable procedures.
+Selecting an agent as a `subagent` is different from inheritance: it exposes a runtime delegation target and does not merge that delegate's identity into the leader.
+See [Agents](./agents.md#inheritance-and-prompt-fragments) for the exact merge and prompt-source rules.
 
 ## Migrating from authored profiles
 
-Earlier Outfitter versions defined profiles as authored YAML files (`.outfitter/profiles/`, `profile.yml`, inheritance, `controls`). That system is removed with no compatibility mode. See the [migration reference](./migration.md) for the manual mapping from the legacy format to agents and their loadouts.
+Earlier Outfitter versions defined profiles as authored YAML files (`.outfitter/profiles/`, `profile.yml`, inheritance, `controls`).
+That system is removed with no compatibility mode.
+See the [migration reference](./migration.md) for the manual mapping from the legacy format to agents and their loadouts.

package/docs/documentation/state.md

@@ -152,7 +152,7 @@ state_persistence:
   trust.json: symlink # Pi trust decisions.
   plugins/: symlink # Pi plugins.
   cache/: symlink # Pi cache data.
-  sessions/: symlink # Pi sessions.
+  sessions/: symlink # Pi sessions; the "Pi sessions" section covers how this works today.
   npm/: symlink # Pi npm package installs.
   git/: symlink # Pi git package checkouts.
   tmp/: symlink # Pi temporary runtime tree; allowed: symlink, discard.
@@ -161,6 +161,33 @@ state_persistence:
   unknown: warn # Undeclared writes; allowed: discard, warn, error, prompt.
 ```
 
+## Pi sessions
+
+Pi stores conversation transcripts under its agent directory, and Outfitter points `PI_CODING_AGENT_DIR` at a baked composition that is deleted when the run ends. So that sessions are not deleted with it, every Pi launch sets `PI_CODING_AGENT_SESSION_DIR` to Pi's own durable per-project session folder:
+
+```text
+~/.pi/agent/sessions/--<your-project-path>--/
+```
+
+This is the same folder a standalone `pi` uses in that project, so history is shared both ways and resuming works after the baked composition is gone:
+
+```sh
+outfitter run                 # first session
+outfitter run -- --continue   # picks up where the previous run left off
+```
+
+The default applies to every Pi launch, interactive or not, so `outfitter run -p '…'` in a script or CI job records a session in the same place. Nothing is copied back after the run: Pi writes straight to the durable directory.
+
+To change or turn off session storage, pass Pi's native flags through, or set the environment variable yourself — Outfitter never overrides a session directory you have already chosen:
+
+```sh
+outfitter run -- --no-session                    # ephemeral: record nothing
+outfitter run -- --session-dir ./.pi/sessions    # keep this project's sessions in the repo
+PI_CODING_AGENT_SESSION_DIR=/workspace/.pi/agent/sessions outfitter run
+```
+
+The last form is how a resident or in-cluster agent keeps continuity across restarts: point the variable at a persistent volume.
+
 ## Claude Code state paths
 
 The Claude Code adapter declares these paths:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.",
   "type": "module",
   "repository": {

package/src/schemas/agent.schema.json

@@ -8,6 +8,29 @@
     "name": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 64 },
     "label": { "type": "string", "minLength": 1 },
     "description": { "type": "string" },
+    "inherits": {
+      "oneOf": [
+        { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 64 },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 64 }
+        }
+      ],
+      "description": "Parent agent slug or ordered parent slug list composed parent-first before this agent."
+    },
+    "system_prompt": {
+      "$ref": "#/$defs/promptSource",
+      "description": "Prompt fragment that replaces the winning root system-prompt.md; file is trusted catalog content and repo_file is untrusted repository content."
+    },
+    "append_system_prompt": {
+      "oneOf": [{ "$ref": "#/$defs/promptSource" }, { "type": "array", "items": { "$ref": "#/$defs/promptSource" } }],
+      "description": "Prompt fragments appended after root agents.md and before inherited agent bodies."
+    },
+    "prompt_template": {
+      "$ref": "#/$defs/promptSource",
+      "description": "Harness prompt-template source projected only by harnesses that support templates."
+    },
     "skills": {
       "$ref": "#/$defs/slugList",
       "description": "Skill slugs resolved from agents/<name>/skills first, then catalog-wide skills."
@@ -44,6 +67,15 @@
     "slugList": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 }
+    },
+    "promptSource": {
+      "type": "object",
+      "oneOf": [{ "required": ["file"] }, { "required": ["repo_file"] }],
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "repo_file": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
     }
   }
 }