@ai-outfitter/outfitter 1.14.0 → 1.15.0

package/docs/documentation/settings.md

@@ -27,8 +27,8 @@ isolation: inherit # inherit (default) or isolated; see below. Honored only from
 
 # Where protocol resources come from, beyond this tree and ~/.agents.
 sources:
-  - github: ai-outfitter/.agent # owner/repo shorthand
-    ref: 2f9c1ab0d3e44b6f9d2c8a17e5b40c91d6f3a8e2 # pin a commit, tag, or branch
+  - github: ai-outfitter/community-profiles # owner/repo shorthand
+    ref: v1.7.0 # pin a commit, tag, or branch
     # path: optional subdirectory containing the payload
   - uri: git+https://git.example.com/team/agents.git
     ref: v1.2.0
@@ -52,6 +52,22 @@ source_cache:
 # Pseudonymous product analytics consent; defaults to true when absent.
 telemetry:
   enabled: false
+
+# Additive loadout entries composed into every agent ahead of its own loadout.
+agent_defaults:
+  extensions:
+    - git:github.com/ai-outfitter/pensieve@4b1e0d2c9a7f35e86b0d1c4a92f6e3d5a8b7c601
+  skills:
+    - organization-practices
+  mcp:
+    - github
+  append_system_prompt:
+    - file: prompts/organization.md
+
+# Native harness settings shared by every agent run.
+harness_defaults:
+  pi:
+    httpIdleTimeoutMs: 3600000
 ```
 
 - `default_agent` / `default_harness` — which agent plain `outfitter` runs, and the harness it launches in.
@@ -66,6 +82,8 @@ telemetry:
   accesses the network.
   below its `repos/` directory.
 - `telemetry.enabled` — the primary and sole persistent control for pseudonymous product analytics. Edit it directly to enable or disable telemetry. See [Telemetry](./telemetry.md) for consent precedence, automatic identifier cleanup, the event contract, and the current inert-build status.
+- `agent_defaults` — additive loadout entries composed into **every** agent ahead of its own loadout; see [Agent defaults](#agent-defaults) below.
+- `harness_defaults` — native Pi, Claude Code, or Codex settings applied to every run of that harness; see [Harness defaults](#harness-defaults) below.
 
 ## Precedence
 
@@ -78,4 +96,51 @@ Higher wins:
 5. Cached remote settings (in configured order)
 6. Built-in defaults
 
-Scalar settings override. `sources` follows last-wins ordering per scope so a higher-precedence file replaces the complete lower-precedence list. `workflows` is additive: loaded settings contribute an ordered-set union, and repeated slugs across files collapse to their first occurrence.
+Scalar settings override. `sources` follows last-wins ordering per scope so a higher-precedence file replaces the complete lower-precedence list. `workflows` and `agent_defaults` are additive ordered-set unions. `harness_defaults` deep-merges by harness, with higher-precedence leaves replacing lower-precedence leaves.
+
+## Agent defaults
+
+`agent_defaults` composes one set of additive loadout entries into every agent — local runs, Actions, and dumps alike — so an organization declares a shared extension, skill, MCP server, plugin, delegate, or appended prompt fragment once instead of duplicating it into every `agents/<id>/agent.md`:
+
+```yaml
+agent_defaults:
+  extensions:
+    - git:github.com/ai-outfitter/pensieve@4b1e0d2c9a7f35e86b0d1c4a92f6e3d5a8b7c601
+  skills:
+    - organization-practices
+  mcp:
+    - github
+  plugins:
+    - org-plugin
+  subagents:
+    - org-reviewer
+  append_system_prompt:
+    - file: prompts/organization.md # resolved like agent prompt sources: catalog `file`, active-project `repo_file`
+```
+
+Composition rules:
+
+- Defaults compose **before** each agent's own loadout — like a root-most ancestor ahead of the whole inheritance chain — using the same deterministic parent-first ordering and stable de-duplication as inherited agent loadouts. An agent that lists the same slug itself never duplicates it, and the settings layer wins first-encounter conflicts.
+- Selections resolve catalog-wide across layers, never through an agent's local namespace.
+- Only the additive loadout fields above are supported. Per-agent controls such as `model`, `thinking`, and `tools` stay agent-owned; `agents.md` remains shared prompt context, not a configuration manifest.
+- `outfitter run`, `outfitter dump`, and `outfitter validate` compose the same effective defaults. Unresolved references are validation findings and composition warnings named `agent_defaults …`, and `outfitter dump` records the settings-layer provenance in `.outfitter/composition.json` plus a `settings.yml` carrying the merged defaults, so a dumped tree stays self-contained.
+- Settings without `agent_defaults` behave exactly as before. The block is backend-neutral: no backend-specific keys, endpoints, or credentials.
+
+## Harness defaults
+
+`harness_defaults` keeps organization- or project-wide native coding-harness policy beside the portable agent catalog without putting harness-specific keys in every agent profile:
+
+```yaml
+harness_defaults:
+  pi:
+    httpIdleTimeoutMs: 3600000
+  claude:
+    includeCoAuthoredBy: false
+  codex:
+    features:
+      apps: false
+```
+
+The keys below each harness are passed through as that harness's native settings. `outfitter run` merges Pi and Claude defaults into its temporary `settings.json`; a Pi profile's own configuration overlay remains higher precedence. Codex receives flattened `--config key=TOML` arguments. `outfitter link` manages the same values individually in Pi or Claude `settings.json` and Codex `config.toml`, leaving every unrelated native setting untouched. An unmanaged value is never adopted or overwritten.
+
+Every loaded settings scope may contribute defaults. Objects deep-merge from low to high precedence, while arrays and scalar leaves replace. `outfitter dump` carries the effective block into the dumped tree. Unknown harness names are rejected; supported names are `pi`, `claude`, and `codex`.

package/docs/documentation/state.md

@@ -246,6 +246,6 @@ state_persistence:
 
 When a path uses `symlink`, the durable destination is the native CLI state location — `~/.pi/agent/...` for Pi, `~/.claude/...` for Claude Code. The native location is not another configuration layer: it does not participate in resolution or merge precedence; it only provides a durable destination for state paths.
 
-For a [ported Claude Code setup](./porting-claude.md), `~/.claude` configuration entries are themselves symlinks into `~/.agents/`, so persisted configuration state lands in the protocol tree while session and auth state stays native.
+For a [linked Claude Code home](./linking-harnesses.md), the managed `~/.claude` configuration entries are themselves symlinks into `~/.agents/`, so persisted configuration state lands in the protocol tree while session and auth state stays native.
 
 For the complete adapter contract and rationale, see [State writeback strategy](../architecture/state_writeback_strategy.md).

package/docs/documentation/support-matrix.md

@@ -45,11 +45,12 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 - **MCP servers (Partial)** — selected stdio fields (`command`, `args`, `env`, `cwd`) and streamable HTTP fields (`url`, `headers`) become repeated TOML-valued `-c mcp_servers.<id>.<key>=...` overrides. Server ids must contain only letters, digits, `_`, or `-`; other ids cannot be expressed by Codex `-c` key paths and are skipped with a warning. Legacy SSE and other HTTP transport types are also skipped with a warning. User and project `config.toml` servers remain active because Codex has no strict MCP isolation mode, so every launch warns that projection is additive, even when no servers are selected.
 - **Stdio environment safety** — `${ENV_NAME}` becomes an `env_vars` reference only when the stdio `env` key is also `ENV_NAME`; a reference that would rename the variable is dropped with a warning. Literal values pass through `env` and are visible in process arguments.
 - **HTTP header safety** — `${ENV_NAME}` becomes an `env_http_headers` reference, while `Authorization: Bearer ${ENV_NAME}` becomes `bearer_token_env_var`. Other header values pass through `http_headers` and are visible in process arguments. Outfitter warns for every literal stdio environment or HTTP header entry exposed in argv, so use environment references for secrets.
+- **Persistent links** — [`outfitter link`](./linking-harnesses.md) places managed skills, custom prompts (from commands), the shared-context `AGENTS.md`, and MCP servers registered through `codex mcp add` into `$CODEX_HOME` (default `~/.codex`), so plain `codex` sessions carry the composition without a launch. Agent identities are warned about and not linked, since Codex has no native agent definitions.
 
 ## Claude Code notes
 
 - **Your configuration comes first** — by default a Claude run stands on the configuration already on the machine. Outfitter sets no `CLAUDE_CONFIG_DIR`; it declares the baked composition a Claude plugin and passes it through `--plugin-dir`, so the session keeps your workspace trust, `~/.claude/settings.json` permissions, credentials, plugins, and configured MCP servers, and the profile's skills, subagents, and prompts layer on top. Nothing is seeded and nothing is copied back, because Claude is reading and writing its real configuration directory throughout. Pass `--isolated`, or set `isolation: isolated` in your `~/.agents/settings.yml`, to launch from the composition alone — the reproducible form for CI and containers, and what the remaining bullets in this section describe. If the installed Claude is too old to load a plugin directory, Outfitter falls back to an isolated run and says so rather than failing the launch.
-- **Isolated config and session state** — an isolated run points `CLAUDE_CONFIG_DIR` at the baked composition. Before launch it copies only the current working directory's history from `~/.claude/projects/<project-slug>/` into the projection, so native `--continue` and `--resume` work without exposing other projects. After every successful or failed launch it atomically merges new or changed session files from every projected slug back into `~/.claude/projects/` with mode `0600`, never deleting durable history. Session bridge failures warn without masking the Claude exit. Outfitter also declares Claude state paths (`settings.json`, `agents/`, `skills/`, `commands/`, `plugins/`, `projects/`) for [state persistence](./state.md), and can [symlink a ported `~/.claude`](./porting-claude.md) so native use keeps working. MCP configuration from that port is no longer auto-discovered by Outfitter-launched Claude runs; those servers apply only when an agent selects them by slug. See the next bullet.
+- **Isolated config and session state** — an isolated run points `CLAUDE_CONFIG_DIR` at the baked composition. Before launch it copies only the current working directory's history from `~/.claude/projects/<project-slug>/` into the projection, so native `--continue` and `--resume` work without exposing other projects. After every successful or failed launch it atomically merges new or changed session files from every projected slug back into `~/.claude/projects/` with mode `0600`, never deleting durable history. Session bridge failures warn without masking the Claude exit. Outfitter also declares Claude state paths (`settings.json`, `agents/`, `skills/`, `commands/`, `plugins/`, `projects/`) for [state persistence](./state.md), MCP servers configured in `~/.claude` are not auto-discovered by Outfitter-launched Claude runs; those servers apply only when an agent selects them by slug. See the next bullet.
 - **Credentials, onboarding, and workspace trust** — before launch, Outfitter copies `~/.claude/.credentials.json` to the temporary root as `.credentials.json` with mode `0600`. The projected `.claude.json` contains `oauthAccount` and `hasCompletedOnboarding` when those keys are present in durable `~/.claude.json`. It also contains `projects[<cwd>].hasTrustDialogAccepted: true` only when that exact accepted trust decision already exists there; other projects and unrelated machine state are not copied. After any successful or failed launch, a `.credentials.json` changed by the run is copied back wholesale and `oauthAccount` is atomically merged into durable `.claude.json` without replacing unrelated keys. If the durable credentials also changed after seeding, Outfitter preserves that concurrent refresh and warns instead of copying back. MCP OAuth tokens live under `mcpOAuth` in `.credentials.json`, keyed by `<serverName>|<hash>`, so authorizations acquired in an Outfitter-launched Claude session persist across runs. Other projected `.claude.json` state, including trust accepted during the session, is discarded; a workspace that has never been trusted by native Claude therefore prompts again on every run.
 - **MCP servers** — every Claude launch passes the generated `mcp.json` through `--mcp-config`. An inherited run stops there, so the composition's servers merge with the ones already configured on the machine: selecting a server says what the profile needs, not what the user may not have. An isolated run adds `--strict-mcp-config`, which excludes MCP servers from user or project configuration, `.claude.json`, and plugins so only the composition's servers are active.
 - **Subagents** — selected `agents/<id>` definitions are materialized into the composition's agents directory. An inherited run loads them under the plugin's name (`<profile>:<subagent>`); an isolated run finds them natively under `CLAUDE_CONFIG_DIR`.
@@ -59,6 +60,7 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 - **Tool availability** — `tools.allow` (after `tools.deny` removes entries) maps to both `--tools` (_availability_: an unlisted builtin is not in the session) and `--allowedTools` (_permission_: the granted tools are pre-approved, so a headless session is not stopped by a prompt); `tools.deny` always maps to `--disallowedTools`, including when both are declared, and a bare denied name removes the tool from context per Claude's docs. An allowlist that `tools.deny` empties maps to `--tools ""`, Claude's documented "disable all tools" form. Caveat: per the CLI reference, `--tools` governs the built-in set only — MCP tools (`mcp__server__*`) are unaffected and are governed by which MCP servers the loadout selects, so `--tools ""` is not exactly pi's zero-tool session when MCP servers are present. Claude's behavior here comes from `claude --help` and the CLI reference, not local measurement.
 - **DeepWork jobs** — job selection is Pi-only today and warns on Claude.
 - **Bundled Outfitter skill** — every launch also publishes Outfitter's own self-documentation skill as a bundled plugin, so the agent can explain Outfitter and this launch's configuration.
+- **Persistent links** — [`outfitter link`](./linking-harnesses.md) places managed skills, generated agent definitions, commands, the shared-context `CLAUDE.md`, and user-scope MCP servers into `$CLAUDE_CONFIG_DIR` (default `~/.claude`), so plain `claude` sessions carry the composition without a launch.
 
 ## Pi notes
 

package/docs/documentation/switching-to-outfitter.md

@@ -6,7 +6,7 @@ This guide is for people who already use Pi, Claude Code, Codex, Cursor, or anot
 
 **You already have a `.agents/` directory.** You're done with the hard part — Outfitter reads the protocol directly. Set `default_agent` in `.agents/settings.yml` to one of your [agent](./agents.md) slugs — the agent's own loadout selects its skills, subagents, and knowledge — and run `outfitter`. Nothing is converted or re-authored.
 
-**Your setup lives in `~/.claude`.** Let `outfitter setup` port it into `~/.agents/` and symlink it back so Claude Code keeps working natively — see [Porting a Claude Code setup](./porting-claude.md). Your ported skills, agents, and commands are then referenceable by slug like any protocol resource.
+**Your setup lives in `~/.claude`.** Move it into `~/.agents/` and run `outfitter link` so Claude Code keeps working natively from the tree — see [Linking into Claude Code and Codex](./linking-harnesses.md). Your migrated skills, agents, and commands are then referenceable by slug like any protocol resource.
 
 Starting from neither? `outfitter setup` bootstraps from the default catalog — see [Getting started](./getting-started.md).
 

package/docs/documentation/usecases/shared-conventions.md

@@ -40,7 +40,7 @@ The value is ambiguity reduction: every agent — and every skill that clones, o
 
 ## Reaching native harness runs
 
-Composition only helps runs that go through it — the rule should also reach a bare `claude` session that never touches Outfitter. The porting design ([Porting a Claude Code setup](../porting-claude.md)) maps `~/.claude/CLAUDE.md` to `~/.agents/agents.md` with a symlink back, so native Claude Code reads the protocol tree and editing either view edits the same file; managed porting and persistent harness symlinks — including the generalization of projecting composed shared context into each harness's home-level memory file — are deferred to [#187](https://github.com/ai-outfitter/outfitter/issues/187).
+Composition only helps runs that go through it — the rule should also reach a bare `claude` session that never touches Outfitter. [`outfitter link`](../linking-harnesses.md) symlinks `~/.claude/CLAUDE.md` (and `~/.codex/AGENTS.md`) to the winning `~/.agents/agents.md`, so native Claude Code and Codex read the protocol tree and editing the tree edits what they see. This is the persistent projection [#187](https://github.com/ai-outfitter/outfitter/issues/187) deferred; setup still creates no links.
 
 ## Payoff
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.",
   "type": "module",
   "repository": {
@@ -47,6 +47,7 @@
     "cross-spawn": "^7.0.6",
     "liquidjs": "^10.27.0",
     "posthog-node": "^5.49.1",
+    "smol-toml": "^1.8.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/src/schemas/settings.schema.json

@@ -103,7 +103,54 @@
     "custom_settings": {
       "type": "object",
       "description": "Arbitrary YAML-compatible values exposed to Outfitter composition templates as outfitter.custom_settings."
+    },
+    "agent_defaults": {
+      "type": "object",
+      "description": "Additive loadout entries composed into every agent before its own loadout, using the same deterministic ordering and stable de-duplication as inherited agent loadouts.",
+      "properties": {
+        "extensions": { "$ref": "#/$defs/slugList" },
+        "skills": { "$ref": "#/$defs/slugList" },
+        "mcp": { "$ref": "#/$defs/slugList" },
+        "plugins": { "$ref": "#/$defs/slugList" },
+        "subagents": { "$ref": "#/$defs/slugList" },
+        "append_system_prompt": {
+          "oneOf": [
+            { "$ref": "#/$defs/promptSource" },
+            { "type": "array", "items": { "$ref": "#/$defs/promptSource" } }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "harness_defaults": {
+      "type": "object",
+      "description": "Harness-native settings applied to every composed agent and persistently reconciled by outfitter link.",
+      "properties": {
+        "pi": { "$ref": "#/$defs/nativeSettings" },
+        "claude": { "$ref": "#/$defs/nativeSettings" },
+        "codex": { "$ref": "#/$defs/nativeSettings" }
+      },
+      "additionalProperties": false
     }
   },
-  "additionalProperties": true
+  "additionalProperties": true,
+  "$defs": {
+    "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
+    },
+    "nativeSettings": {
+      "type": "object",
+      "description": "A harness-native settings document. Native keys are validated by the selected harness release."
+    }
+  }
 }

package/docs/documentation/porting-claude.md

@@ -1,58 +0,0 @@
-# Porting a Claude Code setup
-
-If your agent configuration lives in `~/.claude`, Outfitter can port it into `~/.agents/` — the protocol's global layer — and symlink it back so Claude Code keeps working natively while the `.agents` tree becomes the source of truth.
-
-```bash
-outfitter setup
-```
-
-Setup detects an existing `~/.claude` directory (when no `~/.agents/` tree exists yet) and offers the port. Nothing is destroyed: originals are moved, not copied-and-diverged, and the symlinks keep native Claude Code behavior identical.
-
-## What gets ported
-
-| `~/.claude` content      | `~/.agents/` destination | Symlinked back? |
-| ------------------------ | ------------------------ | --------------- |
-| `agents/<id>.md`         | `agents/<id>/agent.md`   | Yes             |
-| `skills/<id>/`           | `skills/<id>/`           | Yes             |
-| `commands/`              | `commands/`              | Yes             |
-| `CLAUDE.md`              | `agents.md`              | Yes             |
-| MCP server configuration | `mcp.json`               | Yes             |
-
-After the port, `~/.claude/skills` is a symlink into `~/.agents/skills`, and so on — Claude Code reads exactly what it read before, from the protocol tree. Editing either view edits the same files.
-
-## What stays native
-
-Runtime and account state is not configuration and stays in `~/.claude` untouched:
-
-- auth and account state
-- sessions and project history (`projects/`)
-- plugins, caches, debug output
-- `settings.json` — permissions, model, and hooks remain harness-native; see [Hooks](./hooks.md) for how hook wiring relates to the tree
-
-This is the same boundary [state persistence](./state.md) enforces at run time: configuration lives in the tree, mutable state lives with the harness.
-
-Staying native does not mean being ignored. A Claude run inherits this state by default, so the
-permissions, hooks, plugins, trust, and MCP servers listed above apply to an Outfitter-launched
-session exactly as they do to a native one. `--isolated` is what leaves them behind.
-
-## After porting
-
-Your resources are now protocol resources. Reference them by slug from an agent's loadout like anything else:
-
-```
-<!-- ~/.agents/agents/daily/agent.md -->
----
-name: daily
-skills: [wiki, code-review] # formerly ~/.claude/skills/*
----
-```
-
-- `outfitter list` shows everything that resolved from the ported tree.
-- `outfitter run daily --harness claude` launches Claude Code through Outfitter with the same material, now composable with catalogs and other layers.
-- Plain `claude` continues to work as before, through the symlinks.
-
-Consider putting `~/.agents` under version control as a standalone repository — see [Local development](./local-development.md).
-
-## Projects
-
-The same port applies per project: a `<repo>/.claude` directory ports to `<repo>/.agents/` (the workspace layer) with symlinks back, and a `CLAUDE.md` at the repo root can become `.agents/agents.md`. Commit the `.agents/` tree; gitignore `.agents/settings.local.yml`.