@ai-outfitter/outfitter 0.11.0 → 1.0.2

package/docs/documentation/state.md

@@ -1,8 +1,8 @@
 # State persistence
 
-Outfitter launches agent CLIs from a temporary composite profile. During a run, Pi, Claude Code, or another adapter may write state such as settings, sessions, plugin installs, caches, auth metadata, or MCP configuration.
+Outfitter launches agent CLIs from a temporary baked composition. During a run, Pi, Claude Code, or another adapter may write state such as settings, sessions, plugin installs, caches, auth metadata, or MCP configuration.
 
-Outfitter does not silently copy every file back into your profiles. Instead, each adapter declares the state paths it understands, chooses safe defaults, and lets profiles override how writes to those paths are handled.
+Outfitter does not silently copy every file back into your `.agents` tree. Instead, each adapter declares the state paths it understands, chooses safe defaults, and lets settings override how writes to those paths are handled.
 
 ## Default behavior
 
@@ -18,40 +18,33 @@ state_persistence:
   mcp.json: symlink # MCP/server configuration stays durable.
   plugins/: symlink # Installed plugins can be reused.
   cache/: symlink # Useful package/cache state can be reused.
-  sessions/: symlink # Session/project state is durable unless a profile overrides it.
-  unknown: warn # Unexpected writes are visible and not silently copied into a profile.
+  sessions/: symlink # Session/project state is durable unless overridden.
+  unknown: warn # Unexpected writes are visible and not silently persisted.
 ```
 
-Some generated Pi runtime files, such as transformed settings or keybindings, may be treated as one-run generated files even though the underlying state path normally defaults to `symlink`. This keeps Outfitter-managed launch reconciliation from becoming accidental user state.
+Some generated runtime files, such as transformed settings or keybindings, may be treated as one-run generated files even though the underlying state path normally defaults to `symlink`. This keeps Outfitter-managed launch reconciliation from becoming accidental user state.
 
 ## How state works
 
 Outfitter separates runtime files into three groups:
 
-1. **Generated profile files** — files Outfitter builds from settings, profiles, templates, and adapter rules. These are temporary and reproducible.
+1. **Generated composition files** — files Outfitter bakes from the resolved `.agents` layers and adapter rules. These are temporary and reproducible.
 2. **Declared state paths** — files or directories the selected agent CLI is expected to read or write, such as `settings.json`, `mcp.json`, `plugins/`, or `sessions/`.
 3. **Unknown writes** — anything the agent writes outside declared state paths. Outfitter never silently persists these because it does not know their owner or merge rules.
 
-Only declared state paths can be persisted automatically.
+Only declared state paths can be persisted automatically. Baked artifacts and [dumps](./dump-and-bake.md) never contain persisted state — state is runtime, not configuration.
 
-## Profile option
+## Configuring persistence
 
-Use `state_persistence` in a profile to override adapter defaults:
+Set `state_persistence` in [settings](./settings.md) — globally, per project, or in `settings.local.yml` for one machine:
 
 ```yaml
-id: strict-ci
-label: Strict CI
-
-# Omitted paths use the selected adapter's default strategy.
-# This profile only overrides paths where CI should be stricter than normal.
+# .agents/settings.yml — a stricter policy for a CI project
 state_persistence:
   settings.json: error # Fail if the agent changes settings during the run.
   mcp.json: error # Fail if tool/server config changes during the run.
   plugins/: error # Fail if plugin state changes during the run.
   unknown: error # Fail if the agent writes an undeclared file.
-
-controls:
-  thinking: high
 ```
 
 ## Strategies
@@ -60,24 +53,22 @@ controls:
 
 ```yaml
 state_persistence:
-  auth.json: symlink # Persist writes through a durable profile-managed or native CLI path.
+  auth.json: symlink # Persist writes through a durable native CLI path.
   cache/: discard # Allow writes, then throw them away when the run ends.
   plugins/: warn # Allow writes, discard them, and report them after the run.
   settings.json: error # Allow the run, then fail if this path changed.
-  mcp.json: prompt # Ask after the run: persist, discard, or always persist for this profile.
+  mcp.json: prompt # Ask after the run: persist, discard, or always persist.
 ```
 
-Use `symlink` for state you want to keep, such as login state, durable settings, MCP config, or plugin installs. Use `discard`, `warn`, or `error` for state that should not become part of the durable profile. Use `prompt` when you want to decide interactively after each run.
+Use `symlink` for state you want to keep, such as login state, durable settings, MCP config, or plugin installs. Use `discard`, `warn`, or `error` for state that should not become durable. Use `prompt` when you want to decide interactively after each run.
 
 ## Prompt strategy
 
 When a `prompt` path changed during a run and both stdin and stdout are interactive terminals, Outfitter asks what to do with the change after the agent exits:
 
-- **persist** — copy the change to the path's durable source (the profile-managed file or the native CLI location) for this run only.
-- **discard** — throw the change away with the rest of the composite profile.
-- **always** — persist the change and record a `state_persistence: <path>: symlink` override in the selected profile's own YAML file, so future runs persist writes to that path automatically.
-
-The "always" choice is written into the selected profile's `profile.yml` because profiles are the single source of truth for `state_persistence` policy. If the selected profile comes from a remote or cached source, Outfitter never mutates the cache: the change is persisted once and a warning explains that the choice could not be recorded.
+- **persist** — copy the change to the path's durable destination for this run only.
+- **discard** — throw the change away with the rest of the baked composition.
+- **always** — persist the change and record a `state_persistence: <path>: symlink` override in the editable settings scope, so future runs persist writes to that path automatically. Outfitter never mutates a synced catalog cache: if the active configuration comes from a remote source, the change is persisted once and a warning explains that the choice could not be recorded.
 
 In non-interactive sessions (CI, scripts, piped stdio), `prompt` falls back to `warn` and Outfitter prints an explicit `prompt skipped: non-interactive` notice.
 
@@ -85,7 +76,7 @@ Undeclared writes governed by `unknown: prompt` cannot be persisted because they
 
 ## Temporary directory cleanup
 
-Composite profile directories are created under the system temporary directory and removed automatically when the Outfitter process exits or receives a handled signal. Removal deletes symlink entries without following them, so the durable auth/settings state the links point at is never touched. Pass `--debug` to keep the directory for inspection; Outfitter prints its path.
+Baked composition directories are created under the system temporary directory and removed automatically when the Outfitter process exits or receives a handled signal. Removal deletes symlink entries without following them, so the durable auth/settings state the links point at is never touched. Pass `--debug` to keep the directory for inspection; Outfitter prints its path.
 
 Each startup also best-effort sweeps `outfitter-*` directories older than seven days from the temporary root. The sweep never follows symlinks, so a stale directory's links are removed while their targets survive.
 
@@ -104,7 +95,7 @@ state_persistence:
 ### Keep shared catalogs clean
 
 ```yaml
-# Story: A team publishes a shared engineering profile catalog.
+# Story: A team publishes a shared .agents catalog.
 # Goal: MCP config can come from the catalog, but one user's random runtime files
 # should not become shared team state.
 state_persistence:
@@ -115,12 +106,12 @@ state_persistence:
 ### Make CI reproducible
 
 ```yaml
-# Story: A platform engineer runs an Outfitter profile in CI.
-# Goal: CI should prove the profile is complete, not depend on hidden runtime mutation.
+# Story: A platform engineer runs a baked Outfitter task in CI.
+# Goal: CI should prove the composition is complete, not depend on hidden runtime mutation.
 state_persistence:
-  settings.json: error # Settings drift means the profile is incomplete.
+  settings.json: error # Settings drift means the composition is incomplete.
   mcp.json: error # Tool config drift should fail the job.
-  plugins/: error # Plugin installs/updates should be explicit in the profile.
+  plugins/: error # Plugin installs/updates should be explicit in the tree.
   unknown: error # Any undeclared write is a reproducibility problem.
 ```
 
@@ -186,39 +177,10 @@ state_persistence:
   unknown: warn # Undeclared writes; allowed: discard, warn, error, prompt.
 ```
 
-Claude Code project/session state is represented through `projects/`. If a profile sets `controls.session_directory` or `controls.claude.session_directory`, Outfitter uses that location for Claude project state.
-
 ## Where durable state lives
 
-When a path uses `symlink`, Outfitter looks for a matching file or directory under the selected profile's CLI-specific resources:
-
-```text
-profiles/
-  default/
-    profile.yml
-    cli_specific/
-      pi/
-        settings.json
-        mcp.json
-      claude/
-        settings.json
-        skills/
-```
-
-If no profile-managed source exists, Outfitter falls back to the native CLI state location for most paths, such as `~/.pi/agent/...` for Pi or `~/.claude/...` for Claude Code.
+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.
 
-This fallback is not another profile layer. It does not participate in inheritance, merge precedence, or profile controls; it only provides a durable destination for state paths.
-
-## When to change defaults
-
-Most users can keep the adapter defaults. Override `state_persistence` when you need a profile with a specific state policy:
-
-```yaml
-state_persistence:
-  cache/: discard # Throwaway demos, sessions, or caches.
-  plugins/: warn # Local experimentation is okay but should be visible.
-  settings.json: error # CI, reproducibility checks, or locked-down project profiles.
-  auth.json: symlink # Intentional durable setup.
-```
+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 the complete adapter contract and rationale, see [State writeback strategy](../architecture/state_writeback_strategy.md).

package/docs/documentation/subagents.md

@@ -0,0 +1,37 @@
+# Subagents
+
+A subagent is a protocol [agent](./agents.md) projected into the harness's native delegation mechanism, so a run can hand focused work to a separate context. You declare subagents in an agent's loadout — the `subagents` field of its `agent.md` frontmatter or `config.json` — not in any settings map.
+
+```markdown
+---
+name: engineer
+subagents: [code-reviewer, explorer]
+---
+```
+
+Each slug resolves to an `agents/<id>/` definition across layers like any other resource. At launch the adapter projects the selected definitions into the harness's subagent surface:
+
+- **Claude Code** — materialized into the harness's agents directory so they are invocable as native subagents.
+- **Pi** — registered through Pi's subagent extension mechanism.
+
+See the [adapter support matrix](./support-matrix.md) for current coverage.
+
+## Leader agents and delegation targets
+
+The reason to give an agent subagents is to make it a **leader**: an agent that coordinates work and delegates the bounded pieces. A leader can delegate two ways, and the two compose:
+
+- **To local coding-harness subagents** — agents projected into the running harness (Claude Code's agents directory, Pi's subagent extension). The leader hands off exploration, review, or parallelizable work to a fresh context on the same machine and gets the result back inline.
+- **To issue- and action-backed subagents** — work dispatched asynchronously, backed by a GitHub issue and an [Outfitter action](./actions.md). The leader files the unit of work as an issue; an action runs the delegate agent headlessly and reports back on the issue or PR. This is how a leader parallelizes across machines and across time rather than within one session.
+
+A leader's loadout is where both are declared: local delegates as `subagents`, remote work routed through the action it triggers. Keep each delegate bounded — one job, clear inputs, a defined deliverable back to the caller.
+
+## When to give an agent subagents
+
+- **One focused agent** — a single agent doing the work directly. Prefer this default; delegation adds latency and context loss.
+- **One leader managing subagents** — a coordinating agent that delegates exploration, review, or parallelizable work.
+
+## Authoring guidance
+
+- Give each subagent a crisp `description` — the leader uses it to decide when to delegate.
+- Keep subagents bounded: one job, clear inputs, a defined deliverable.
+- Don't duplicate skill procedures into subagent definitions; a subagent can select and use [skills](./skills.md) through its own loadout like any agent.

package/docs/documentation/support-matrix.md

@@ -1,49 +1,54 @@
 # Adapter support matrix
 
-What Outfitter can control per agent CLI today. Pi is the primary and most complete adapter; Claude Code is supported with gaps.
+What Outfitter can project per agent CLI. Pi is the primary and most complete adapter; Claude Code is supported with gaps.
 
 Status values:
 
-- **Supported** — Outfitter translates this concept for the CLI through at least one native mechanism.
+- **Supported** — Outfitter projects this concept for the CLI through at least one native mechanism.
 - **Partial** — some of the concept works today, with documented gaps.
-- **Roadmap** — the CLI appears to support the concept, but Outfitter does not translate it yet.
-
-When a profile requests a control an adapter cannot translate, Outfitter warns to stderr; `--strict` makes those warnings fatal.
-
-| What you can control                              | Pi        | Claude Code |
-| ------------------------------------------------- | --------- | ----------- |
-| Agent config directory                            | Supported | Supported   |
-| Session directory (`session_directory`)           | Supported | Supported   |
-| Extensions / plugins (`extensions`)               | Supported | Supported   |
-| Skills (`skills`)                                 | Supported | Partial     |
-| Prompt templates / commands (`prompt_template`)   | Supported | Partial     |
-| System prompt (`system_prompt`)                   | Supported | Supported   |
-| Appended system prompt (`append_system_prompt`)   | Supported | Supported   |
-| Model selection (`model`, `provider`, `thinking`) | Supported | Partial     |
-| Credentials and environment (`environment`)       | Supported | Supported   |
-| Tool availability                                 | Roadmap   | Roadmap     |
-| Context files                                     | Roadmap   | Roadmap     |
-| Theme / UI presentation                           | Roadmap   | Roadmap     |
-| Project override policy                           | Roadmap   | Roadmap     |
-| Working directory                                 | Roadmap   | Roadmap     |
-| Pass-through arguments                            | Supported | Supported   |
-| Bootstrap hook                                    | Supported | Roadmap     |
+- **Roadmap** — the CLI appears to support the concept, but Outfitter does not project it yet.
+
+When a composition requests something an adapter cannot project, Outfitter warns to stderr; `--strict` makes those warnings fatal.
+
+Tasks and bake are not in this matrix — they are the subject of a [separate upcoming RFC](./tasks.md).
+
+| What Outfitter projects                                                  | Pi        | Claude Code |
+| ------------------------------------------------------------------------ | --------- | ----------- |
+| Agent config directory                                                   | Supported | Supported   |
+| Session directory                                                        | Supported | Supported   |
+| Agent identity (`system-prompt.md`, `agents.md`, `agents/<id>/agent.md`) | Supported | Supported   |
+| Subagents (`agents/<id>` as harness delegates)                           | Supported | Supported   |
+| Skills (`skills/<id>`)                                                   | Supported | Partial     |
+| Commands (`commands/`)                                                   | Supported | Partial     |
+| Knowledge (`knowledge/`)                                                 | Supported | Partial     |
+| Model selection (`models.json`)                                          | Supported | Partial     |
+| MCP servers (`mcp.json`)                                                 | Supported | Supported   |
+| Extensions (agent `extensions:` loadout)                                 | Supported | Roadmap     |
+| Plugins (agent `plugins:` loadout)                                       | Supported | Roadmap     |
+| Credentials and environment                                              | Supported | Supported   |
+| DeepWork job selection                                                   | Supported | Roadmap     |
+| Hooks                                                                    | Partial   | Partial     |
+| Tool availability                                                        | Roadmap   | Roadmap     |
+| Theme / UI presentation                                                  | Roadmap   | Roadmap     |
+| Working directory                                                        | Roadmap   | Roadmap     |
+| Pass-through arguments                                                   | Supported | Supported   |
+| Bootstrap hook                                                           | Supported | Roadmap     |
 
 ## Claude Code notes
 
-- **Config and session state** — Outfitter points `CLAUDE_CONFIG_DIR` at the composite profile, declares Claude state paths (`settings.json`, `agents/`, `skills/`, `commands/`, `plugins/`, `projects/`) for persistence, and lets `session_directory` choose where `projects/` session state is symlinked from. There is no standalone session-dir flag.
-- **Skills (Partial)** — native Claude skills work when a profile ships them as `cli_specific/claude/skills/` directories, which Outfitter places in the profiled config directory. The generic `controls.skills` selector (including catalog skill IDs) is not translated for Claude yet and warns if requested; the bundled Outfitter skill ships through the plugin channel instead.
-- **Prompt templates (Partial)** — same shape: native `cli_specific/claude/commands/` directories work, but the generic `controls.prompt_template` selector is not translated and warns.
-- **Model selection (Partial)** — `model` maps to `--model` and `thinking` maps to `--effort`, but `provider` is not translated for Claude and warns if requested.
-- **Extensions** — `controls.extensions` entries are passed as repeated `--plugin-dir` flags.
-- **Bundled Outfitter skill** — every launch also publishes Outfitter's own self-documentation skill (authored at `.outfitter/skills/outfitter` in the Outfitter repository) as a bundled plugin through `--plugin-dir`, so the agent can explain Outfitter and this launch's configuration.
-- **DeepWork jobs** — the `controls.deepwork` selection is Pi-only today and warns on Claude.
+- **Config and session state** — Outfitter points `CLAUDE_CONFIG_DIR` at the baked composition, 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.
+- **Subagents** — selected `agents/<id>` definitions are materialized into Claude's native agents directory.
+- **Skills (Partial)** — selected skills are materialized into the config directory's skills surface; remaining gaps are tracked per release. The bundled Outfitter skill ships through the plugin channel.
+- **Model selection (Partial)** — model maps to `--model` and thinking level to `--effort`; provider selection is not projected for Claude and warns if requested.
+- **Hooks (Partial)** — hook configuration is projected into the generated `settings.json`; there is no portable protocol hooks resource yet. See [Hooks](./hooks.md).
+- **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.
 
 ## Pi notes
 
-- Pi translates the full generic control set: `provider`, `model`, `thinking`, `system_prompt`, `append_system_prompt`, `extensions` (`--extension`), `skills` (`--skill`), `prompt_template` (`--prompt-template`), `environment`, `args`, `session_directory`, and DeepWork job selection.
-- **Catalog skills** — `controls.skills` entries may be catalog skill IDs (bare strings or `{ id, references }` objects). Outfitter resolves IDs across project, directory-profile, and configured-source `skills/` directories following layer precedence, materializes `references`, `scripts`, and `assets` frontmatter into a generated skill beneath the composite profile, and passes the generated directory via `--skill`. `outfitter profile lint` validates selections and references before launch.
-- Bootstrap behavior (for example the onboarding flow) uses an explicit Pi bootstrap extension via `--extension`.
-- Every launch also passes Outfitter's own self-documentation skill — materialized with its documentation references into the composite profile — through `--skill`.
+- Pi projects the full resource set: agent identity, subagents (via the subagent extension), skills (`--skill`), commands, model configuration, MCP, extensions (`--extension`) and plugins as first-class loadout elements, environment, pass-through args, session directory, and DeepWork job selection.
+- Selected skills resolve across layers following [layer precedence](./concepts.md#layer-precedence); `references`, `scripts`, and `assets` frontmatter materialize into a generated skill passed via `--skill`. `outfitter validate` checks selections and references before launch.
+- **Hooks (Partial)** — bootstrap behavior uses an explicit Pi extension via `--extension`; recurring per-event hooks are extension territory. See [Hooks](./hooks.md).
+- Every launch also passes Outfitter's own self-documentation skill through `--skill`.
 
 For the architecture-level definitions behind each row, see [Controllable elements](../architecture/controllable-elements.md).

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

@@ -1,14 +1,22 @@
 # Switching to Outfitter
 
-This guide is for people who already use Pi, Claude Code, Codex, Cursor, or another agent CLI and want Outfitter to make that setup repeatable. The goal is not to copy every local experiment into a profile. The goal is to capture the small set of habits that reliably jumpstart the human.
+This guide is for people who already use Pi, Claude Code, Codex, Cursor, or another agent CLI and want Outfitter to make that setup repeatable. The goal is not to copy every local experiment into the tree. The goal is to capture the small set of habits that reliably jumpstart the human.
+
+## Two adoption paths
+
+**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.
+
+Starting from neither? `outfitter setup` bootstraps from the default catalog — see [Getting started](./getting-started.md).
 
 ## Migration shape
 
 1. Keep the current agent CLI installed and working.
 2. Identify the behavior you rely on every week: prompts, planning rules, permission posture, skills, subagents, and state you want preserved.
-3. Create one Outfitter home profile for stable personal defaults.
-4. Add project overlays only where a repository needs different instructions or tools.
-5. Run `outfitter`, compare the session to your old workflow, and tighten the profile before adding more controls.
+3. Put stable personal defaults in your global layer — ideally a versioned standalone `.agents` repo ([Local development](./local-development.md)).
+4. Add a project `.agents/` overlay only where a repository needs different instructions or tools.
+5. Run `outfitter`, compare the session to your old workflow, and tighten the tree before adding more.
 
 ## What to migrate first
 
@@ -19,105 +27,91 @@ Migrate durable operating rules before migrating files:
 - how it should use subagents;
 - what review or test evidence you expect;
 - what writing voice or product judgment it should preserve;
-- which skills/extensions are essential.
+- which skills are essential.
 
-Leave transient chat tricks behind. If a rule is not worth committing to a profile, it probably belongs in the next prompt, not the baseline.
+Leave transient chat tricks behind. If a rule is not worth committing to the tree, it probably belongs in the next prompt, not the baseline.
 
-## Home profile template
+## Global layer template
 
-Use this as a commented migration worksheet. The comments are intentionally user-facing: they encode the human jumpstart idea and the writing nucleation seed that should make a fresh session feel like your best existing setup.
-
-```yaml
-# ~/.outfitter/settings.yml
-# Human jumpstart: this default profile should make `outfitter` feel like
-# your current best agent setup, but with fewer manual launch steps.
-default_profile: migrated-agent-workbench
-default_agent: pi
-profile_sources:
-  - path: ./profiles
+Use this as a migration worksheet: one agent holding your durable posture and the skills you reach for.
 
+```
+<!-- ~/.agents/agents/workbench/agent.md -->
 ---
-# ~/.outfitter/profiles/migrated-agent-workbench/profile.yml
-id: migrated-agent-workbench
-label: Migrated Agent Workbench
-# Name the workflow this replaces: "Claude Code defaults", "Codex review mode", etc.
-description: Personal agent-CLI habits migrated into an Outfitter-managed Pi profile.
-
-controls:
-  # YOLO posture: grant routine local autonomy while keeping irreversible work gated.
-  append_system_prompt: |
-    You may inspect files, make focused edits, and run local validation commands.
-    Ask before deleting files, changing dependencies, pushing, publishing, touching credentials,
-    mutating production data, or making irreversible external changes.
-
-    Plan before broad rewrites. Use acceptance criteria that can be checked from repo state.
-    Prefer small commits and explain validation evidence before calling work done.
-
-    Writing nucleation: treat rough notes as source material, not final requirements.
-    Convert ambiguous requests into a short plan, preserve interesting claims, and remove filler.
-
-  # Keep controls minimal during migration. Add model/thinking/tool settings only when
-  # they represent a stable preference rather than a one-off experiment.
-  thinking: high
-
-  # Skills can come from Pi packages, the Outfitter default profile catalog, or project profiles.
-  # Add only skills you expect to use repeatedly.
-  skills: []
-
-  # Subagents may be provided by the active Pi/Outfitter profile or project config.
-  # Document how you want the lead agent to use them even before adding custom definitions.
+name: workbench
+description: Personal agent-CLI habits migrated from my previous setup.
+skills: [] # add only skills you expect to use repeatedly
+---
+
+# Workbench
+
+You may inspect files, make focused edits, and run local validation commands.
+Ask before deleting files, changing dependencies, pushing, publishing, touching
+credentials, mutating production data, or making irreversible external changes.
+
+Plan before broad rewrites. Use acceptance criteria that can be checked from
+repo state. Prefer small commits and explain validation evidence before
+calling work done.
+
+Treat rough notes as source material, not final requirements: convert
+ambiguous requests into a short plan, preserve interesting claims, remove filler.
+```
+
+```yaml
+# ~/.agents/settings.yml
+default_agent: workbench
+default_harness: pi
 ```
 
 ## Project overlay template
 
-Use a project overlay when a repository has instructions that should not leak into every session.
+Use a project overlay when a repository has instructions that should not leak into every session. The workspace layer merges over your global layer by ID; `agents.md` carries project context.
 
-```yaml
-# <repo>/.outfitter/settings.yml
-# Project jumpstart: select the repo-specific profile when `outfitter` starts here.
-default_profile: project-workbench
-profile_sources:
-  # Import the home profile this project inherits from.
-  # Adjust the relative path to match the repo's depth under your home directory.
-  - path: ../../.outfitter/profiles
-    only:
-      - migrated-agent-workbench
-  - path: ./profiles
+```
+<!-- <repo>/.agents/agents.md -->
 
----
-# <repo>/.outfitter/profiles/project-workbench/profile.yml
-id: project-workbench
-label: Project Workbench
-inherits:
-  - migrated-agent-workbench
-controls:
-  append_system_prompt: |
-    Use this repository's docs, tests, and issue tracker as the source of truth.
-    Record durable decisions in project files, not only in chat.
-    Run the narrowest relevant validation before broad checks.
+Use this repository's docs, tests, and issue tracker as the source of truth.
+Record durable decisions in project files, not only in chat.
+Run the narrowest relevant validation before broad checks.
+```
+
+A project overlay can add a skill to the workbench agent without redefining it. Put the additive loadout change in the agent's `config.json`: JSON files shallow-merge by key across layers, so the workspace layer adds `deployment-review` while the global `agent.md` identity stays intact. (A partial `agent.md` would _not_ merge field-by-field — it resolves whole-resource by ID and would replace the global body, so keep loadout tweaks in `config.json`.)
+
+```
+<!-- <repo>/.agents/agents/workbench/config.json -->
+{
+  "skills": ["deployment-review"]
+}
+```
+
+```yaml
+# <repo>/.agents/settings.yml
+default_agent: workbench
 ```
 
 ## Mapping old habits to Outfitter
 
-| Existing habit                       | Outfitter/Pi shape                                                                                       |
+| Existing habit                       | Outfitter shape                                                                                          |
 | ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| “Always plan before edits.”          | Use the plan extension keybinding (`Shift+Tab` in the default Outfitter Pi setup) before implementation. |
-| “Use YOLO except dangerous actions.” | State allowed local actions and approval gates in the profile.                                           |
-| “Run code review after changes.”     | Add or enable a review skill, then invoke it inside Pi with a slash command such as `/skill:review`.     |
-| “Spawn a second agent for research.” | Add subagent guidance and use available subagent definitions when active.                                |
-| “Use browser or GitHub helpers.”     | Load the Pi extension/tool package through the profile that needs it.                                    |
-| “Keep project context durable.”      | Commit project instructions to `AGENTS.md`; keep personal defaults in the Outfitter home profile.        |
-| “Keep a project-specific prompt.”    | Add a project overlay that inherits the home profile.                                                    |
+| "Always plan before edits."          | Use the plan extension keybinding (`Shift+Tab` in the default Outfitter Pi setup) before implementation. |
+| "Use YOLO except dangerous actions." | State allowed local actions and approval gates in your agent.                                            |
+| "Run code review after changes."     | Select a review skill, then invoke it with a slash command such as `/skill:review`.                      |
+| "Spawn a second agent for research." | Select an explorer [subagent](./subagents.md) and describe when the lead agent should delegate.          |
+| "Use browser or GitHub helpers."     | Add the MCP server to `mcp.json` in the layer that needs it.                                             |
+| "Keep project context durable."      | Commit it to the project's `.agents/agents.md`; keep personal defaults in your global layer.             |
+| "Repeat the same CI/automation job." | Make it a [task](./tasks.md) with structured inputs.                                                     |
 
 ## Check the active capabilities
 
-Because tools differ by CLI and profile, start migrated sessions with:
+Because tools differ by CLI and composition, start migrated sessions with:
 
 ```text
-List the active tools, skills, extensions, and subagents. Note which are vanilla Pi, which come from Outfitter's default profile catalog, and which are project-local. Also read AGENTS.md if this repo has one.
+List the active tools, skills, and subagents. Note which are vanilla harness
+features, which come from the default catalog, and which are project-local.
+Also read agents.md if this tree has one.
 ```
 
-If a capability only exists because a Pi extension is active, document that in the profile or project README. If a behavior is a project rule rather than a personal preference, put it in `AGENTS.md` so every agent session can inherit it.
+If a behavior is a project rule rather than a personal preference, put it in the project's `.agents/agents.md` so every agent session can inherit it.
 
 ## Migration checkpoint
 
@@ -127,4 +121,4 @@ Run:
 outfitter
 ```
 
-If the first session does not feel like a better version of your old setup, edit the prompt seed before adding more files. The first win is reliable launch plus useful starting context; broader profile catalogs can come after that baseline holds.
+If the first session does not feel like a better version of your old setup, edit the agent before adding more files. The first win is reliable launch plus useful starting context; broader catalogs can come after that baseline holds.

package/docs/documentation/tasks.md

@@ -0,0 +1,13 @@
+# Tasks
+
+> **Status: future RFC.** Tasks are not part of the dotagents end state described here. This page is a placeholder for a concept that will be specified separately.
+
+A task is intended to be a named, portable execution contract — the stable objective of a repeatable unit of work, the resources it composes, its structured input and output contract, and what "done" means — together with a **bake** step that freezes that contract and its inputs into an immutable, deterministic artifact for headless execution (CI, scheduled jobs, delegated work).
+
+That surface — `tasks/<id>/task.md`, structured `inputs`, `outfitter task bake`, and task-backed [actions](./actions.md) — raises its own design questions (input trust boundaries, determinism guarantees, DeepWork job selection, adapter coverage) and will be worked out in a dedicated RFC rather than folded into this one.
+
+Until then:
+
+- Run work interactively by selecting an [agent](./agents.md): `outfitter run <agent-id>`.
+- Inspect exactly what an agent composes with [`outfitter dump`](./dump-and-bake.md).
+- For headless GitHub Actions runs today, see [Actions](./actions.md), which runs an agent non-interactively with structured inputs.