@ai-outfitter/outfitter 0.11.0 → 1.0.2

package/.outfitter/skills/outfitter/SKILL.md

@@ -1,20 +1,33 @@
 ---
 name: outfitter
-description: Explain Outfitter and help users create, inspect, and maintain Outfitter profiles, settings, skills, and setup sources. Use when a user asks about Outfitter itself — profiles, profile.yml files, profile sources and catalogs, skills, state persistence, launch configuration — or asks to set up, change, or debug an Outfitter-managed launch.
+description: Explain Outfitter and help users compose, inspect, and maintain .agents resources, agents and their loadouts, personas, skills, and settings. Use when a user asks about Outfitter itself — the .agents protocol, agent profiles and personas, catalogs, skills, state persistence, launch configuration — or asks to set up, change, debug, or migrate an Outfitter-managed launch.
 
+# TODO: once directory reference materialization lands, collapse the list
+# below to a single `- file: docs/documentation` entry so the whole
+# documentation tree ships with this skill. Kept per-file until then.
 references:
   - file: docs/documentation/README.md
   - file: docs/documentation/getting-started.md
   - file: docs/documentation/concepts.md
+  - file: docs/documentation/settings.md
   - file: docs/documentation/cli.md
   - file: docs/documentation/profiles.md
-  - file: docs/documentation/profile-repository.md
+  - file: docs/documentation/personas.md
+  - file: docs/documentation/subagents.md
+  - file: docs/documentation/agents.md
   - file: docs/documentation/skills.md
+  - file: docs/documentation/tasks.md
+  - file: docs/documentation/dump-and-bake.md
+  - file: docs/documentation/catalogs.md
   - file: docs/documentation/state.md
   - file: docs/documentation/support-matrix.md
   - file: docs/documentation/best-practices.md
   - file: docs/documentation/actions.md
+  - file: docs/documentation/hooks.md
   - file: docs/documentation/switching-to-outfitter.md
+  - file: docs/documentation/porting-claude.md
+  - file: docs/documentation/local-development.md
+  - file: docs/documentation/migration.md
   - file: docs/documentation/first-time-cli-agent-users.md
   - file: docs/documentation/iterating-on-profiles.md
 ---
@@ -22,36 +35,54 @@ references:
 # Outfitter
 
 Use this skill to answer questions about Outfitter and to guide changes to
-Outfitter-managed profiles, settings, and launches. Classify the request, read
-only the relevant reference, and follow its cross-references before answering
-or editing configuration.
+`.agents` resources, agents and their loadouts, and launches. Classify the
+request, read only the relevant reference, and follow its cross-references
+before answering or editing configuration.
 
 ## Routing
 
 - New to Outfitter, installing, or first launch: read
   `references/getting-started.md`.
-- How a launch works — settings, profile resolution, layering, composite
-  profiles: read `references/concepts.md`.
-- Command flags and syntax for `outfitter run`, `setup`, `sync`, or
-  `profile ...`: read `references/cli.md`.
-- Writing or editing profiles, profile layouts, inheritance, prompt includes:
-  read `references/profiles.md`.
-- Shared profile catalogs, setup sources, publishing profiles or skills for
-  other users: read `references/profile-repository.md`.
+- How a launch works — the `.agents` protocol, layers, resolver, composition:
+  read `references/concepts.md`.
+- Settings scopes, schema, or `settings.local.yml`: read
+  `references/settings.md`.
+- Command flags and syntax for `outfitter run`, `setup`, `sync`, `list`,
+  `validate`, or `dump`: read `references/cli.md`.
+- Agent profiles — an agent and its loadout (skills, subagents, mcp,
+  extensions, plugins, model, thinking, tools): read `references/profiles.md`.
+- The `agents/<id>/agent.md` resource format and loadout fields: read
+  `references/agents.md`.
+- Personas — the base-agent-plus-persona-documents convention: read
+  `references/personas.md`.
+- Subagents and leader-agent delegation: read `references/subagents.md`.
 - Authoring or selecting skills, SKILL.md layout, skill references: read
   `references/skills.md`.
+- Tasks and bake (a separate upcoming RFC): read `references/tasks.md`.
+- Dumping the composed tree: read `references/dump-and-bake.md`.
+- Shared catalogs, standalone `.agents` repositories, remote sources,
+  publishing resources: read `references/catalogs.md`.
 - What persists between runs, state persistence strategies, prompt choices:
   read `references/state.md`.
-- What Outfitter can control per agent CLI (pi, Claude Code): read
+- What Outfitter can project per agent CLI (pi, Claude Code): read
   `references/support-matrix.md`.
-- Structuring profiles versus skills, keeping instructions in one place: read
-  `references/best-practices.md`.
-- Running profiles headlessly in GitHub Actions: read `references/actions.md`.
+- Structuring agent identity versus skills, keeping instructions in one place:
+  read `references/best-practices.md`.
+- Running tasks headlessly in GitHub Actions: read `references/actions.md`.
+- Getting hooks working per harness: read `references/hooks.md`.
 - Migrating from another agent CLI setup: read
   `references/switching-to-outfitter.md`.
+- Porting an existing `~/.claude` directory into `~/.agents`: read
+  `references/porting-claude.md`.
+- Developing a personal `.agents` repository and upstreaming changes: read
+  `references/local-development.md`.
+- **Migrating from legacy `.outfitter` profiles** (`profile.yml`,
+  `.outfitter/profiles`, `--profile` file ids): read `references/migration.md`.
+  The runtime has no legacy compatibility; this reference is the manual
+  migration path.
 - Never used a CLI coding agent before: read
   `references/first-time-cli-agent-users.md`.
-- Improving the currently active profile, including this launch's own
+- Improving the currently active agent, including this launch's own
   configuration: read `references/iterating-on-profiles.md`.
 
 `references/README.md` is the documentation index if no entry above fits.
@@ -59,28 +90,27 @@ or editing configuration.
 ## Working on Outfitter configuration
 
 1. Inspect the current configuration before editing:
-   - `.outfitter/settings.yml` and `.outfitter/local/settings.yml`
-   - `.outfitter/profiles/` and `.outfitter/skills/`
-   - `~/.outfitter/settings.yml` and `~/.outfitter/profiles/`
-2. Prefer Outfitter commands over manual file edits:
-   - `outfitter profile list` to inspect available profiles
-   - `outfitter profile create <id> --scope user|project|project-local` to
-     scaffold profiles
-   - `outfitter profile lint` to validate profiles and skill references
-   - `outfitter setup <source>` to import setup sources
-   - `outfitter sync` to refresh remote profile sources
-   - `outfitter run --profile <id>` to verify launch behavior
-3. Keep each instruction in one place: durable operating context belongs in
-   the profile, per-capability procedure belongs in a skill
+   - `.agents/settings.yml` and `.agents/settings.local.yml`
+   - `.agents/agents/` and `.agents/skills/`
+   - `~/.agents/settings.yml` and the `~/.agents/` tree
+2. Prefer Outfitter commands over manual inspection:
+   - `outfitter list` to inspect resolvable resources and their sources
+   - `outfitter validate` to check layout, loadouts, and references
+   - `outfitter setup <source>` to import catalogs
+   - `outfitter sync` to refresh remote sources
+   - `outfitter run <agent-id>` to verify launch behavior
+   - `outfitter dump --out <dir>` to inspect exactly what a run composes
+3. Keep each instruction in one place: durable identity belongs in the agent
+   definition, per-capability procedure belongs in a skill
    (`references/best-practices.md`).
-4. Validate changes with `outfitter profile lint` and, when possible, a smoke
-   test such as `outfitter run --profile <id> -- --help`.
+4. Validate changes with `outfitter validate --strict` and, when possible, a
+   smoke test such as `outfitter run <agent-id> -- --help`.
 
 ## Default behavior
 
 If the user asks for help with Outfitter without a specific request:
 
-1. Run `outfitter profile list` to show available profiles.
-2. Summarize the profiles by name, scope or source, and default status.
-3. Ask whether the user wants to create or change a profile, and read
-   `references/profiles.md` before scaffolding one.
+1. Run `outfitter list agents` to show resolvable agents and resources.
+2. Summarize the agents by name, scope or source, and default status.
+3. Ask whether the user wants to compose or change an agent, and read
+   `references/profiles.md` and `references/agents.md` before editing.

package/README.md

@@ -1,68 +1,96 @@
 # Outfitter
 
-Outfitter builds effective agent profiles and launches them through wrapped agent CLIs like [`pi`](https://github.com/earendil-works/pi-coding-agent), Claude Code, and future adapters. Individuals, teams, and organizations can share and compose repeatable agent profiles.
+Outfitter is the toolchain for the [Dotagents `.agents` protocol](https://dotagentsprotocol.com/): it resolves agent configuration from local and remote `.agents` trees, composes personas, skills, and tasks by slug, bakes tasks into deterministic execution artifacts, and launches the result through wrapped agent CLIs like [`pi`](https://github.com/earendil-works/pi-coding-agent) and Claude Code.
 
-If you have not tried [Pi](https://pi.dev) yet, Outfitter is the quickest path to a recommended Pi loadout for engineering work.
+Outfitter does not own a configuration format. Your `.agents/` directory is the source of truth — useful without Outfitter, committed and reviewed like any other code.
 
-## Quick start
+> **Status:** these docs describe the target architecture of [RFC #165](https://github.com/ai-outfitter/outfitter/issues/165) (protocol revision `502a9d5`). Implementation is landing as a chain of PRs; the released CLI still runs the legacy profile system until then.
 
-The first time outfitter runs it will start the setup flow to choose profiles and setup a model if pi is not already configured with one.
+## Quick start
 
-Run without installing.
+Run without installing:
 
 ```bash
 npx @ai-outfitter/outfitter
 ```
 
-Full install
+Full install:
 
 ```bash
 npm install -g @ai-outfitter/outfitter
 outfitter
 ```
 
-Outfitter launches agent CLIs; install the agents you plan to use separately.
+Pi is bundled and also hosts Outfitter's setup walkthrough. Install other runtime harnesses, such as
+Claude Code, separately. For the full walkthrough, see [Getting started](./docs/documentation/getting-started.md).
 
-For the full walkthrough, see [Getting started](./docs/documentation/getting-started.md).
+## Already have a `.agents/` directory?
 
-## Profiles
+Then you already have Outfitter configuration. Each agent's loadout references your existing skills, subagents, MCP, knowledge, and commands by slug with zero porting:
 
-[Profiles](./docs/documentation/profiles.md) compose the context, tools, prompts, skills, extensions, subagents, and DeepWork workflows that shape an agent. Profiles can be shared using [Profile Catalog Repos](./docs/documentation/profile-repository.md).
+```
+<!-- .agents/agents/engineer/agent.md -->
+---
+name: engineer
+skills: [wiki, research]
+subagents: [code-reviewer]
+mcp: [github]
+---
+```
 
 ```yaml
-# ~/.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.
-    - repo_file: docs/architecture.md
+# .agents/settings.yml
+default_agent: engineer
+```
+
+`outfitter setup` restores the original Pi-native profile-catalog walkthrough on top of `.agents`:
+choose the default Outfitter catalog, create your own profile, or provide another catalog, then pick
+the home/project target and default CLI agent. The default picker is fetched from the immutable
+`ai-outfitter/default-profiles` Release Please tag pinned by Outfitter—never from a sibling checkout.
+Managed porting and persistent harness symlinks are deferred to
+[#187](https://github.com/ai-outfitter/outfitter/issues/187).
+
+## The `.agents` protocol in 30 seconds
+
+```text
+.agents/
+  agents.md            # shared operating context
+  system-prompt.md     # base system prompt
+  mcp.json             # MCP servers
+  models.json          # model configuration
+  agents/<id>/agent.md # identities + loadouts — run directly or as subagents
+  skills/<id>/...      # capability packages
+  knowledge/           # reference documents
+  commands/            # slash commands
 ```
 
+Layers merge by ID: `<project>/.agents/` over `~/.agents/` over pinned remote [catalogs](./docs/documentation/catalogs.md). An [agent](./docs/documentation/agents.md) carries both its identity and its loadout — an [agent profile](./docs/documentation/profiles.md) — and is what you run; a [persona](./docs/documentation/personas.md) is a review convention layered on a base agent; a [subagent](./docs/documentation/subagents.md) is an agent a run delegates to, including through [GitHub Actions](./docs/documentation/actions.md).
+
+Agents can also run headlessly in GitHub Actions via [`ai-outfitter/actions`](https://github.com/ai-outfitter/actions).
+
 ## Documentation
 
 - [Getting started](./docs/documentation/getting-started.md)
-- [What works today: adapter support matrix](./docs/documentation/support-matrix.md)
-- [Profiles](./docs/documentation/profiles.md)
-- [Skills](./docs/documentation/skills.md)
-- [Best practices](./docs/documentation/best-practices.md)
-- [Profile repositories](./docs/documentation/profile-repository.md)
-- [State persistence](./docs/documentation/state.md)
-- [First-time CLI agent users](./docs/documentation/first-time-cli-agent-users.md)
-- [Switching to Outfitter](./docs/documentation/switching-to-outfitter.md)
+- [Concepts](./docs/documentation/concepts.md)
+- [Settings](./docs/documentation/settings.md)
+- [Agents](./docs/documentation/agents.md) · [Agent profiles](./docs/documentation/profiles.md) · [Personas](./docs/documentation/personas.md) · [Subagents](./docs/documentation/subagents.md)
+- [Skills](./docs/documentation/skills.md) · [Tasks (future RFC)](./docs/documentation/tasks.md)
+- [Catalogs](./docs/documentation/catalogs.md) · [Dump](./docs/documentation/dump-and-bake.md)
+- [Running an agent in GitHub Actions](./docs/documentation/actions.md)
+- [Hooks](./docs/documentation/hooks.md) · [State persistence](./docs/documentation/state.md)
+- [Adapter support matrix](./docs/documentation/support-matrix.md)
+- [Local dotagents development](./docs/documentation/local-development.md)
+- [Switching to Outfitter](./docs/documentation/switching-to-outfitter.md) · [Migration from legacy profiles](./docs/documentation/migration.md)
 - [Documentation index](./docs/documentation/README.md)
 
 Use cases:
 
-- [Organization profile catalog](./docs/documentation/usecases/organization-profile-catalog.md) — Publish shared team roles so new users can start with organization-approved defaults.
-- [Engineering profile catalog](./docs/documentation/usecases/engineering.md) — Package coding, platform, and review profiles for repeatable engineering workflows.
-- [Persona reviews](./docs/documentation/usecases/persona-reviews.md) — Create customer personas to get feedback on ideas, documentation, and designs.
+- [Organization catalog](./docs/documentation/usecases/organization-profile-catalog.md) — Publish shared org resources and defaults through an `owner/.outfitter` control repository.
+- [Engineering catalog](./docs/documentation/usecases/engineering.md) — Package engineering personas, skills, and tasks for repeatable workflows.
+- [Persona reviews](./docs/documentation/usecases/persona-reviews.md) — Compose customer personas to get feedback on ideas, documentation, and designs.
 
 For local development, repository structure, and release workflow details, see [Contributing](./CONTRIBUTING.md).
+
+## License
+
+Outfitter is [MIT licensed](./LICENSE.md), except for code in `code/enterprise/`, which is under the [Unsupervised Enterprise license](./code/enterprise/LICENSE). Production use of that code requires a valid Unsupervised Enterprise license.

package/code/enterprise/cli/privateCatalogSettings.cjs

@@ -27,7 +27,7 @@ const enablePrivateProfileCatalogs = (settingsPath) => {
       ...document,
       enterprise: {
         ...enterprise,
-        private_profile_catalogs: true,
+        private_catalogs: true,
       },
     }),
   );
@@ -38,7 +38,7 @@ const readPrivateProfileCatalogsSetting = (value) => {
     return undefined;
   }
 
-  return value.enterprise?.private_profile_catalogs;
+  return value.enterprise?.private_catalogs;
 };
 
 const readSettingsRecord = (settingsPath) => {

package/code/enterprise/pi-extension/privateCatalogOnboarding.js

@@ -20,27 +20,24 @@ export const confirmPrivateCatalog = async (ctx, selectDescribedOption, reposito
 export const readPrivateProfileCatalogsEnabled = (fs, settingsPath) => {
   if (!fs.existsSync(settingsPath)) return false;
   const content = fs.readFileSync(settingsPath, 'utf8');
-  return /^enterprise:\s*(?:\n\s+[A-Za-z0-9_-]+:\s*[^\n]*)*\n\s+private_profile_catalogs:\s*true\s*$/mu.test(content);
+  return /^enterprise:\s*(?:\n\s+[A-Za-z0-9_-]+:\s*[^\n]*)*\n\s+private_catalogs:\s*true\s*$/mu.test(content);
 };
 
 export const writePrivateProfileCatalogsEnabled = (fs, settingsPath) => {
   fs.mkdirSync(fs.dirname(settingsPath), { recursive: true });
   const content = fs.existsSync(settingsPath) ? fs.readFileSync(settingsPath, 'utf8') : '';
-  if (/^\s*private_profile_catalogs:\s*(?:true|false)\s*$/mu.test(content)) {
+  if (/^\s*private_catalogs:\s*(?:true|false)\s*$/mu.test(content)) {
     fs.writeFileSync(
       settingsPath,
-      content.replace(/^\s*private_profile_catalogs:\s*(?:true|false)\s*$/gmu, '  private_profile_catalogs: true'),
+      content.replace(/^\s*private_catalogs:\s*(?:true|false)\s*$/gmu, '  private_catalogs: true'),
     );
     return;
   }
   if (/^enterprise:\s*$/mu.test(content)) {
-    fs.writeFileSync(
-      settingsPath,
-      content.replace(/^enterprise:\s*$/mu, 'enterprise:\n  private_profile_catalogs: true'),
-    );
+    fs.writeFileSync(settingsPath, content.replace(/^enterprise:\s*$/mu, 'enterprise:\n  private_catalogs: true'));
     return;
   }
-  fs.writeFileSync(settingsPath, content.replace(/\s*$/u, '\n') + 'enterprise:\n  private_profile_catalogs: true\n');
+  fs.writeFileSync(settingsPath, content.replace(/\s*$/u, '\n') + 'enterprise:\n  private_catalogs: true\n');
 };
 
 export const classifyGitHubRepositoryVisibility = async (repository) => {

package/code/enterprise/shared/privateCatalogPolicy.cjs

@@ -18,15 +18,15 @@ const formatPrivateCatalogCliPrompt = (repository) =>
     'Private profile catalog support is covered by the Outfitter Enterprise license.',
     'Review code/enterprise/LICENSE or your enterprise agreement before enabling.',
     '',
-    'Enable private profile catalogs in ~/.outfitter/settings.yml? [y/N] ',
+    'Enable private profile catalogs in ~/.agents/settings.yml? [y/N] ',
   ].join('\n');
 
 const formatPrivateCatalogSkippedMessage = (repository, interactive) =>
   interactive
     ? `info: Private profile catalog setup was skipped for ${repository}; no settings were changed.`
-    : `info: Private GitHub profile catalog detected: ${repository}. Enable enterprise.private_profile_catalogs in ~/.outfitter/settings.yml after reviewing code/enterprise/LICENSE or your enterprise agreement.`;
+    : `info: Private GitHub profile catalog detected: ${repository}. Enable enterprise.private_catalogs in ~/.agents/settings.yml after reviewing code/enterprise/LICENSE or your enterprise agreement.`;
 
-const privateCatalogEnabledMessage = 'info: Enabled private profile catalogs in ~/.outfitter/settings.yml.';
+const privateCatalogEnabledMessage = 'info: Enabled private profile catalogs in ~/.agents/settings.yml.';
 
 const formatPrivateCatalogSkipResultMessage = (repository) =>
   `Private profile catalog setup was skipped for ${repository}; no settings were changed.`;
@@ -35,7 +35,7 @@ const privateCatalogPiPromptItems = Object.freeze([
   Object.freeze({
     value: 'enable',
     label: 'Enable and continue',
-    description: 'Write enterprise.private_profile_catalogs: true to ~/.outfitter/settings.yml and save this catalog.',
+    description: 'Write enterprise.private_catalogs: true to ~/.agents/settings.yml and save this catalog.',
   }),
   Object.freeze({
     value: 'cancel',
@@ -50,7 +50,7 @@ const formatPrivateCatalogPiPromptTitle = (repository) => [
   'Private profile catalog support is covered by the Outfitter Enterprise license.',
   'Review code/enterprise/LICENSE or your enterprise agreement before enabling.',
   '',
-  'Enable private profile catalogs in ~/.outfitter/settings.yml and use this catalog?',
+  'Enable private profile catalogs in ~/.agents/settings.yml and use this catalog?',
 ];
 
 module.exports = {