@ai-outfitter/outfitter 0.7.2 → 0.8.0

package/doc/documentation/profiles.md

@@ -0,0 +1,183 @@
+# Profiles
+
+Profiles define the accoutrements that shape an Outfitter-managed agent launch.
+
+A profile can compose:
+
+- context and prompts
+- model and provider settings
+- Pi extensions
+- skills
+- subagents
+- DeepWork workflows
+- agent-specific CLI flags and environment variables
+
+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.
+
+## 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
+```
+
+`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.
+
+Profile-owned file includes resolve from the source root of the profile layer that declares the entry, including inherited layers:
+
+| 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 |
+
+`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.
+
+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.
+
+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:
+
+```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
+
+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.
+```

package/doc/documentation/state.md

@@ -0,0 +1,204 @@
+# 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 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.
+
+## Default behavior
+
+Most users do not need to configure `state_persistence` at all. By default, Outfitter keeps known agent CLI state durable and reports unexpected writes.
+
+```yaml
+# This is the behavior most users get without writing any state_persistence block.
+# Known Pi and Claude Code state paths default to symlink, so normal setup survives.
+# Unknown writes default to warn, so surprising files are reported instead of silently persisted.
+state_persistence:
+  auth.json: symlink # Pi login/auth state survives future runs.
+  settings.json: symlink # Native CLI settings stay durable.
+  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.
+```
+
+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.
+
+## 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.
+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.
+
+## Profile option
+
+Use `state_persistence` in a profile to override adapter defaults:
+
+```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.
+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
+
+`state_persistence` values can be:
+
+```yaml
+state_persistence:
+  auth.json: symlink # Persist writes through a durable profile-managed or 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 # Reserved for future interactive handling; currently diagnostic where allowed.
+```
+
+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.
+
+## User stories
+
+### Keep login working
+
+```yaml
+# Story: A developer connects Pi to a model provider during first-run setup.
+# Goal: The next `outfitter` launch remembers the login instead of asking again.
+state_persistence:
+  auth.json: symlink # Keep provider login/auth metadata durable.
+  models.json: symlink # Keep discovered/configured model metadata durable.
+```
+
+### Keep shared catalogs clean
+
+```yaml
+# Story: A team publishes a shared engineering profile catalog.
+# Goal: MCP config can come from the catalog, but one user's random runtime files
+# should not become shared team state.
+state_persistence:
+  mcp.json: symlink # Keep intentional tool/server config durable.
+  unknown: warn # Report unexpected writes instead of silently sharing them.
+```
+
+### 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.
+state_persistence:
+  settings.json: error # Settings drift means the profile is incomplete.
+  mcp.json: error # Tool config drift should fail the job.
+  plugins/: error # Plugin installs/updates should be explicit in the profile.
+  unknown: error # Any undeclared write is a reproducibility problem.
+```
+
+### Avoid cross-project leakage
+
+```yaml
+# Story: A consultant switches between client repositories.
+# Goal: Sessions, caches, and temp files from one client should not show up in another.
+state_persistence:
+  sessions/: discard # Throw away conversation/session state after the run.
+  cache/: discard # Throw away cache data tied to this run.
+  tmp/: discard # Throw away temporary runtime artifacts.
+  unknown: warn # Still report surprising writes for investigation.
+```
+
+### Experiment without losing visibility
+
+```yaml
+# Story: An engineer tries new plugins or package installs locally.
+# Goal: Let the experiment run, but report what changed so the user can decide
+# whether to make it durable later.
+state_persistence:
+  plugins/: warn # Allow plugin changes, but do not persist silently.
+  unknown: warn # Surface other writes that may need a policy.
+```
+
+## Pi state paths
+
+The Pi adapter declares these paths:
+
+```yaml
+state_persistence:
+  auth.json: symlink # Login/auth state; allowed: symlink, error, prompt.
+  settings.json: symlink # Pi settings; generated launch transforms may be one-run.
+  keybindings.json: symlink # Pi keybindings; Outfitter may generate launch keybindings.
+  mcp.json: symlink # MCP/server configuration.
+  models.json: symlink # Model/provider metadata.
+  trust.json: symlink # Pi trust decisions.
+  plugins/: symlink # Pi plugins.
+  cache/: symlink # Pi cache data.
+  sessions/: symlink # Pi sessions.
+  npm/: symlink # Pi npm package installs.
+  git/: symlink # Pi git package checkouts.
+  tmp/: symlink # Pi temporary runtime tree; allowed: symlink, discard.
+  utilities/: symlink # Shared utility binaries such as rg/fd.
+  bin/: symlink # Utility binary links.
+  unknown: warn # Undeclared writes; allowed: discard, warn, error, prompt.
+```
+
+## Claude Code state paths
+
+The Claude Code adapter declares these paths:
+
+```yaml
+state_persistence:
+  settings.json: symlink # Claude Code settings.
+  agents/: symlink # Claude agent definitions.
+  skills/: symlink # Claude skills.
+  commands/: symlink # Claude commands/prompts.
+  plugins/: symlink # Claude plugins.
+  projects/: symlink # Claude project/session state.
+  debug/: symlink # Claude debug state.
+  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.
+
+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 the complete adapter contract and rationale, see [State writeback strategy](../architecture/state_writeback_strategy.md).

package/doc/documentation/support-matrix.md

@@ -0,0 +1,46 @@
+# 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.
+
+Status values:
+
+- **Supported** — Outfitter translates 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     |
+
+## 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 is not translated for Claude and warns if requested.
+- **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.
+- **DeepWork jobs** — the `controls.deepwork` selection is Pi-only today and warns on Claude.
+
+## 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.
+- Bootstrap behavior (for example the onboarding flow) uses an explicit Pi bootstrap extension via `--extension`.
+
+For the architecture-level definitions behind each row, see [Controllable elements](../architecture/controllable-elements.md).

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

@@ -0,0 +1,130 @@
+# 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.
+
+## 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.
+
+## What to migrate first
+
+Migrate durable operating rules before migrating files:
+
+- how much autonomy the agent gets;
+- when it must plan before editing;
+- 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.
+
+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.
+
+## Home profile 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
+
+---
+# ~/.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.
+```
+
+## Project overlay template
+
+Use a project overlay when a repository has instructions that should not leak into every session.
+
+```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>/.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.
+```
+
+## Mapping old habits to Outfitter
+
+| Existing habit                       | Outfitter/Pi 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.                                                    |
+
+## Check the active capabilities
+
+Because tools differ by CLI and profile, 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.
+```
+
+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.
+
+## Migration checkpoint
+
+Run:
+
+```bash
+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.

package/doc/documentation/usecases/engineering.md

@@ -0,0 +1,114 @@
+# Engineering Profile Catalog
+
+An engineering profile catalog is a shared setup source for people who write code, review changes, operate infrastructure, and debug production-like systems. It gives engineers a reliable default Pi session without asking each teammate to rebuild the same model, thinking, prompt, skill, and extension choices by hand.
+
+For example, `acme-engineering-outfitter` can publish a small catalog with profiles for day-to-day implementation, deeper platform work, and lightweight review or triage.
+
+```text
+acme-engineering-outfitter/
+  settings.yml
+  profiles/
+    base-engineering/
+      profile.yml
+    engineer/
+      profile.yml
+    platform-engineer/
+      profile.yml
+    reviewer/
+      profile.yml
+```
+
+## Catalog settings
+
+```yaml
+# acme-engineering-outfitter/settings.yml
+profile_sources:
+  - path: ./profiles
+    only:
+      - engineer
+      - platform-engineer
+      - reviewer
+```
+
+## Shared base profile
+
+```yaml
+# profiles/base-engineering/profile.yml
+id: base-engineering
+label: Engineering Base
+template: true
+description: Shared engineering operating rules for code, tests, and infrastructure.
+controls:
+  append_system_prompt: |
+    Work as a careful engineering agent. Read the relevant code before editing,
+    prefer small reversible changes, keep secrets out of logs, run focused tests,
+    and return changed files plus verification evidence.
+```
+
+## Role profiles
+
+Engineering catalogs SHOULD separate routine implementation from high-risk infrastructure and review work. The examples below are role-shaped; replace model IDs and thinking levels with the exact choices exposed by the team's agent providers.
+
+```yaml
+# profiles/engineer/profile.yml
+id: engineer
+label: Software Engineer
+description: Default for feature work, bug fixes, and test-backed implementation.
+inherits:
+  - base-engineering
+controls:
+  provider: anthropic
+  model: anthropic/claude-sonnet-4
+  thinking: high
+  append_system_prompt: |
+    Optimize for correct, reviewable implementation. Inspect nearby code and tests,
+    make narrow commits, run the smallest meaningful validation, and summarize risks.
+```
+
+```yaml
+# profiles/platform-engineer/profile.yml
+id: platform-engineer
+label: Platform Engineer
+description: Higher-caution profile for CI, infrastructure, deployment, and incident work.
+inherits:
+  - base-engineering
+controls:
+  provider: anthropic
+  model: anthropic/claude-opus-4
+  thinking: xhigh
+  append_system_prompt: |
+    Treat infrastructure and production-like systems as high-risk. Diagnose before
+    mutating state, name rollback paths, and ask before deploys, credential use,
+    payments, or irreversible operations.
+```
+
+```yaml
+# profiles/reviewer/profile.yml
+id: reviewer
+label: Code Reviewer
+description: Review-focused profile for diffs, pull requests, and release readiness.
+inherits:
+  - base-engineering
+controls:
+  provider: openai
+  model: openai/gpt-4.1
+  thinking: medium
+  append_system_prompt: |
+    Review for correctness, regression risk, missing tests, unsafe operations,
+    unclear rollout paths, and documentation drift. Prioritize actionable findings
+    over style nits.
+```
+
+## Verification pattern
+
+Engineering catalogs SHOULD make verification expectations explicit in prompts or comments so agents return evidence instead of vague completion claims.
+
+```yaml
+# profiles/engineer/profile.yml excerpt
+controls:
+  append_system_prompt: |
+    When you change code, report the exact tests or checks you ran. If a check is
+    skipped, say why and name the smallest follow-up validation that would reduce risk.
+```
+
+This gives an engineering team a repeatable catalog with safe defaults: fast enough for common implementation, cautious enough for infrastructure, and explicit about verification evidence.