@ai-outfitter/outfitter 0.11.0 → 1.0.2

package/docs/documentation/profiles.md

@@ -1,183 +1,30 @@
-# Profiles
+# Agent profiles
 
-Profiles define the accoutrements that shape an Outfitter-managed agent launch.
+"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.
 
-A profile can compose:
+## Profiles are agents
 
-- context and prompts
-- model and provider settings
-- Pi extensions
-- skills
-- subagents
-- DeepWork workflows
-- agent-specific CLI flags and environment variables
+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.
 
-Profiles can be local to a user or project, inherited from other profiles, or loaded from a shared profile repository. See [Profile repositories](./profile-repository.md) for shared setup sources.
+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:
 
-## Profile layouts
-
-Outfitter supports two profile layouts inside any configured `profile_sources` directory.
-
-### Flat profile layout
-
-Use the flat layout for small profile catalogs where each profile is mostly YAML and does not need its own resource folder. Each `*.yml` or `*.yaml` file directly under the profile source is a profile. If the file omits `id`, Outfitter uses the filename stem as the profile id.
-
-```text
-~/.outfitter/profiles/
-  founder.yml
-  engineer.yml
-  data-analyst.yaml
-```
-
-```yaml
-# ~/.outfitter/profiles/founder.yml
-label: Founder
-description: Founder-operator defaults for product, engineering, research, and prose.
-controls:
-  append_system_prompt: |
-    Think like a founder-operator: connect product judgment, implementation, and evidence.
-```
-
-Flat profiles are easy to scan, diff, and copy between setup repositories. Generated Pi prompt exports for flat profiles are written beside the flat file as `<profile-id>.generated-system-prompt.md` when `profile_export` is enabled.
-
-### Directory profile layout
-
-The original layout is one folder per profile with a required `profile.yml`. Use it when a profile owns prompts, skills, extensions, DeepWork jobs, or CLI-specific files that should travel with that profile.
-
-```text
-~/.outfitter/profiles/
-  home-default/
-    profile.yml
-    prompts/
-      system.md
-    skills/
-    extensions/
-    deepwork/
-      jobs/
-    cli_specific/
-      pi/
-```
-
-```yaml
-# ~/.outfitter/profiles/home-default/profile.yml
-id: home-default
-label: Home Default
-controls:
-  system_prompt: ./prompts/system.md
-  skills:
-    - ./skills/review
-```
-
-Directory profiles keep bundled resources close to the profile that references them. Generated Pi prompt exports for directory profiles are written as `generated-system-prompt.md` inside the profile directory when `profile_export` is enabled.
-
-## Home and project example
-
-A home profile SHOULD hold reusable defaults for one developer.
-A project profile SHOULD live with the repository and add only the behavior that project needs.
-The comments below name the files; each `---` starts a separate YAML document in the same example block.
-
-```yaml
-# ~/.outfitter/settings.yml
-default_profile: home-default
-default_agent: pi
-profile_sources:
-  - path: ./profiles
-
----
-# ~/.outfitter/profiles/home-default.yml
-id: home-default
-label: Home Default
-description: Reusable personal defaults for Outfitter-managed Pi runs.
-controls:
-  provider: openai-codex
-  model: gpt-5.5
-  thinking: high
-  append_system_prompt:
-    - |
-      Use concise, evidence-backed engineering prose.
-      Prefer small, reviewable changes.
-      Keep durable decisions in repo files.
-    - file: prompts/personal-policy.md
-    - repo_file: docs/mission.md
-
----
-# ~/repos/acme/example/.outfitter/settings.yml
-default_profile: acme-example
-profile_export: true
-profile_sources:
-  # Relative to this settings.yml; exposes ~/.outfitter/profiles to the project.
-  - path: ../../../../.outfitter/profiles
-    only:
-      - home-default
-  - path: ./profiles
-
----
-# ~/repos/acme/example/.outfitter/profiles/acme-example/profile.yml
-id: acme-example
-label: Acme Example
-description: Checked-in project profile for ~/repos/acme/example.
-inherits:
-  - home-default
-controls:
-  thinking: xhigh
-  append_system_prompt:
-    - |
-      You are working in ~/repos/acme/example.
-      Honor the project test contract before calling work complete.
-      Prefer repository-local conventions over personal defaults.
-    - file: .outfitter/prompts/review-policy.md
-  environment:
-    ACME_PROJECT: example
+```bash
+outfitter run engineer
+outfitter run engineer --harness claude
 ```
 
-`home-default` is the home-folder profile: it supplies personal defaults that can work across repositories.
-`acme-example` is the project profile: it inherits those defaults, then overrides the thinking level and adds project-specific prompt and environment settings.
-When a project `settings.yml` declares `profile_sources`, it SHOULD include any home profile source that project profiles inherit from.
-Because `append_system_prompt` composes instead of replacing, the higher-precedence project prompt is passed first and the inherited home prompt follows.
-Typed prompt includes read `{ file: string }` entries before launch and pass the file contents as repeated append-prompt text. Raw strings remain literal prompt text; if a raw string looks like a whole file path, Outfitter warns so the profile can be migrated to `{ file: ... }`.
-
-### Append prompt file includes
-
-`append_system_prompt` accepts a literal string, a multiline string, `{ file: string }`, `{ repo_file: string }`, or an ordered list mixing those entry types. Outfitter does not support `{ text: ... }`; use raw YAML strings for inline prompt text, `{ file: ... }` for maintained profile/catalog files, and `{ repo_file: ... }` for files that should come from the active project.
+`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.
 
-Profile-owned file includes resolve from the source root of the profile layer that declares the entry, including inherited layers:
+## Where the loadout lives
 
-| Declaring profile location                                                         | Include root               |
-| ---------------------------------------------------------------------------------- | -------------------------- |
-| `~/.outfitter/profiles/<id>/profile.yml` or `~/.outfitter/profiles/<id>.yml`       | `~/.outfitter`             |
-| `<project>/.outfitter/profiles/<id>/profile.yml`                                   | `<project>`                |
-| Catalog repo `outfitter/profiles/<id>/profile.yml`                                 | Catalog repository root    |
-| Explicit `profile_sources[].path` without `.outfitter/` or `outfitter/` convention | The configured source path |
+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.
 
-`repo_file:` resolves from the active project directory where Outfitter launches the agent. This lets a reusable catalog or home profile request project-local governance context such as `docs/mission.md` without copying those docs into the catalog.
+Settings ([settings.md](./settings.md)) is left with just resolution and launch concerns — `default_agent`, `default_harness`, `sources`, and state policy — not resource selection.
 
-Run `outfitter profile lint` to report schema and inheritance errors, missing typed include files, and raw string append-prompt entries that look like file paths. Add `--strict` to exit non-zero for warnings, and `--json` for machine-readable diagnostics.
+## Composing from a base
 
-With `profile_export: true`, the selected project directory profile can write `generated-system-prompt.md` beside `profile.yml`.
-For this example, the generated prompt fallback would show the composed prompt inputs like this:
+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 base review agent, many interchangeable persona description documents fed as input.
 
-```text
-<!-- Generated by Outfitter from Pi runtime ctx.getSystemPrompt(). Safe to review or git-ignore. Do not edit by hand. -->
-# Generated Pi runtime system prompt
+## Migrating from authored profiles
 
-You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
-
-Available tools:
-- read: Read file contents
-- bash: Execute bash commands (ls, grep, find, etc.)
-- edit: Make precise file edits with exact text replacement, including multiple disjoint edits in one call
-
-....
-
-## append_system_prompt[0]
-
-You are working in ~/repos/acme/example.
-Honor the project test contract before calling work complete.
-Prefer repository-local conventions over personal defaults.
-
-## append_system_prompt[1]
-
-Use concise, evidence-backed engineering prose.
-Prefer small, reviewable changes.
-Keep durable decisions in repo files.
-```
+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/settings.md

@@ -0,0 +1,61 @@
+# Settings
+
+Outfitter settings configure how resources are resolved and launched. They live inside the `.agents` tree so a tree carries everything it needs, and they are the only Outfitter-specific files in it — deleting them leaves a pure protocol payload.
+
+Settings do not carry resource selections. An agent's loadout — its skills, subagents, model, and so on — lives on the [agent](./agents.md), not here. Settings is only about where resources come from and how a run launches.
+
+## Scopes
+
+| Scope         | File                                                       | Purpose                                                        |
+| ------------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
+| Project-local | `<project>/.agents/settings.local.yml`                     | Personal, uncommitted overrides for one machine. Gitignore it. |
+| Project       | `<project>/.agents/settings.yml`                           | Committed settings shared by everyone on the project.          |
+| User          | `~/.agents/settings.yml` (+ optional `settings.local.yml`) | Personal defaults across projects.                             |
+| Remote        | Cached files from `remote_settings`                        | Organization-distributed defaults.                             |
+
+`settings.local.yml` is a flat file beside `settings.yml` — there is no nested local directory. It overlays its sibling with the same schema and higher precedence, and is the natural home for machine-specific values such as absolute paths to local checkouts (see [Local development](./local-development.md)).
+
+In a standalone `.agents` repository the repository root is the tree, so the files are simply `settings.yml` and `settings.local.yml` at the root.
+
+## Schema
+
+```yaml
+# .agents/settings.yml
+default_agent: engineer # which agent runs by default
+default_harness: pi # which harness to launch: pi or claude
+
+# 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
+    # path: optional subdirectory containing the payload
+  - uri: git+https://git.example.com/team/agents.git
+    ref: v1.2.0
+  - path: ../shared-agents # local directory, read live from disk
+
+# Organization-distributed settings, layered below local settings.
+remote_settings:
+  - github: my-org/.outfitter
+    path: .agents/settings.yml
+    ref: 9c47d1e2b8a05f36c4d7e90a12b3f8c5d6e71a04
+
+cache_directory: ~/.agents/cache
+```
+
+- `default_agent` / `default_harness` — which agent plain `outfitter` runs, and the harness it launches in.
+- `sources` — ordered list of remote or local `.agents` payloads. Remote entries (`github:` / `uri:`) accept `ref:` pinning and an optional `path:` to the payload inside the repository; see [Catalogs](./catalogs.md) for conventions and trust guidance.
+- `remote_settings` — shared settings a repository distributes; cached locally and merged below your project and user settings, so anything you set locally wins.
+- `cache_directory` — where remote sources are cached (`outfitter sync` updates them).
+
+## Precedence
+
+Higher wins:
+
+1. `<project>/.agents/settings.local.yml`
+2. `<project>/.agents/settings.yml`
+3. `~/.agents/settings.local.yml`
+4. `~/.agents/settings.yml`
+5. Cached remote settings (in configured order)
+6. Built-in defaults
+
+Scalar settings override; list-valued settings such as `sources` follow last-wins ordering per scope so a local file can reorder or replace where resources come from.