@ai-outfitter/outfitter 0.11.0 → 1.0.2

package/docs/documentation/usecases/engineering.md

@@ -1,114 +1,97 @@
-# Engineering Profile Catalog
+# Engineering 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.
+An engineering catalog is a shared `.agents` source for people who write code, review changes, operate infrastructure, and debug production-like systems. It gives engineers a reliable default session without asking each teammate to rebuild the same model, prompt, and skill 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.
+For example, `acme-engineering/.agent` can publish a small catalog with agents for day-to-day implementation, deeper platform work, and lightweight review or triage — plus the skills those agents share.
 
 ```text
-acme-engineering-outfitter/
+acme-engineering/.agent/     # repository root is the payload
+  agents.md                  # shared operating rules for every agent in the tree
+  agents/
+    engineer/agent.md
+    platform-engineer/agent.md
+    reviewer/agent.md
+  skills/
+    issue-planning/
+    deployment-review/
   settings.yml
-  profiles/
-    base-engineering/
-      profile.yml
-    engineer/
-      profile.yml
-    platform-engineer/
-      profile.yml
-    reviewer/
-      profile.yml
 ```
 
 ## Catalog settings
 
+Settings only names the default agent; each agent carries its own loadout.
+
 ```yaml
-# acme-engineering-outfitter/settings.yml
-profile_sources:
-  - path: ./profiles
-    only:
-      - engineer
-      - platform-engineer
-      - reviewer
+# settings.yml
+default_agent: engineer
 ```
 
-## Shared base profile
+## Shared operating context
 
-```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.
+Rules that apply to every agent in the tree live in `agents.md`, so each role inherits them without ordered persona composition:
+
+```markdown
+<!-- agents.md -->
+
+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
+## Role agents
 
-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.
+Engineering catalogs SHOULD separate routine implementation from high-risk infrastructure and review work. Each agent declares its skills, model, and thinking level in its own loadout; replace the IDs with the exact choices exposed by the team's providers.
 
-```yaml
-# profiles/engineer/profile.yml
-id: engineer
-label: Software Engineer
+```
+<!-- agents/engineer/agent.md -->
+---
+name: 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.
+skills: [issue-planning]
+---
+
+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.
+```
+<!-- agents/platform-engineer/agent.md -->
+---
+name: platform-engineer
+description: Higher-caution role for CI, infrastructure, deployment, and incident work.
+skills: [deployment-review]
+---
+
+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.
+```
+<!-- agents/reviewer/agent.md -->
+---
+name: reviewer
+description: Review-focused role for diffs, pull requests, and release readiness.
+---
+
+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.
+Engineering catalogs SHOULD make verification expectations explicit 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.
 ```
+<!-- agents/engineer/agent.md excerpt -->
+
+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.
+```
+
+## Repeatable automation
+
+Recurring engineering work — PR review, issue triage, scheduled audits — runs these agents headlessly through [GitHub Actions](../actions.md) with structured inputs. Adding a capability is a skill change; adding a trigger is workflow wiring; neither duplicates the roles. A dedicated task/bake contract for that recurring work is the subject of a [separate upcoming RFC](../tasks.md).
 
 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.

package/docs/documentation/usecases/organization-profile-catalog.md

@@ -1,140 +1,112 @@
-# Organization Profile Catalog
+# Organization Catalog
 
-An organization profile catalog is a shared setup source that publishes named roles instead of asking every user to choose providers, models, thinking levels, extensions, and prompts by hand.
-For example, `acme` can publish a small catalog that gives engineers, platform operators, support staff, and executives a useful default Pi session while still letting projects override the final profile.
+An organization catalog publishes named role agents instead of asking every user to choose models, prompts, skills, and MCP configuration by hand. The convention is an `owner/.outfitter` control repository carrying a protocol `.agents/` payload: `acme/.outfitter` can give engineers, platform operators, support staff, and executives a useful default session while still letting projects override the final composition.
 
 ```text
-acme-outfitter-catalog/
-  settings.yml
-  profiles/
-    base-acme/
-      profile.yml
-    engineer/
-      profile.yml
-    platform-operator/
-      profile.yml
-    support-triage/
-      profile.yml
-    exec-briefing/
-      profile.yml
+acme/.outfitter/
+  .agents/
+    agents.md              # shared Acme operating rules for every role
+    models.json
+    agents/
+      engineer/agent.md
+      platform-operator/agent.md
+      support-triage/agent.md
+      exec-briefing/agent.md
+    settings.yml
 ```
 
 ## Catalog settings
 
+The catalog's `settings.yml` names the default agent; the organization distributes it through [remote settings](./../catalogs.md#organization-control-repositories):
+
 ```yaml
-# acme-outfitter-catalog/settings.yml
-profile_sources:
-  - path: ./profiles
-    only:
-      - engineer
-      - platform-operator
-      - support-triage
-      - exec-briefing
+# acme/.outfitter/.agents/settings.yml
+default_agent: engineer
 ```
 
-## Shared base profile
+## Shared operating context
 
-```yaml
-# profiles/base-acme/profile.yml
-id: base-acme
-label: Acme Base
-template: true
-description: Shared Acme operating rules for every published role.
-controls:
-  append_system_prompt: |
-    Work as an Acme operator: prefer small reversible changes, cite durable evidence,
-    keep secrets out of logs and docs, and write decisions into repository files.
+Rules every role shares live in the tree's `agents.md`, inherited by each agent without ordered persona composition:
+
+```markdown
+<!-- .agents/agents.md -->
+
+Work as an Acme operator: prefer small reversible changes, cite durable
+evidence, keep secrets out of logs and docs, and write decisions into
+repository files.
 ```
 
-## Role profiles
+## Role agents
 
-The catalog SHOULD publish role profiles that make the cost/latency/quality tradeoff explicit.
-Use provider-qualified model IDs that match the models available in the team's Pi or Claude configuration.
-The examples below are intentionally role-shaped; replace model IDs with the exact names exposed by the organization's provider catalog.
+The catalog SHOULD publish role agents that make the cost/latency/quality tradeoff explicit. Model choices live in each agent's `config.json` (or the tree's `models.json`); replace the IDs below with the exact names exposed by the organization's provider catalog.
 
-```yaml
-# profiles/engineer/profile.yml
-id: engineer
-label: Software Engineer
+```
+<!-- .agents/agents/engineer/agent.md -->
+---
+name: engineer
 description: Default for feature work, debugging, tests, and code review.
-inherits:
-  - base-acme
-controls:
-  provider: anthropic
-  model: anthropic/claude-sonnet-4
-  thinking: high
-  append_system_prompt: |
-    Optimize for correct implementation over speed. Read nearby code before editing,
-    run the narrowest meaningful tests, and return changed files plus verification.
+---
+
+Optimize for correct implementation over speed. Read nearby code before
+editing, run the narrowest meaningful tests, and return changed files plus
+verification.
 ```
 
-```yaml
-# profiles/platform-operator/profile.yml
-id: platform-operator
-label: Platform Operator
-description: Higher-reasoning profile for infrastructure, incidents, CI, and release safety.
-inherits:
-  - base-acme
-controls:
-  provider: anthropic
-  model: anthropic/claude-opus-4
-  thinking: xhigh
-  append_system_prompt: |
-    Treat production-like systems as high-risk. Prefer diagnosis before mutation,
-    name rollback paths, and ask before deploys, credential use, payments, or irreversible changes.
+```json
+// .agents/agents/engineer/config.json
+{ "provider": "anthropic", "model": "anthropic/claude-sonnet-4", "thinking": "high" }
 ```
 
-```yaml
-# profiles/support-triage/profile.yml
-id: support-triage
-label: Support Triage
-description: Lower-cost profile for ticket summarization, reproduction notes, and routing.
-inherits:
-  - base-acme
-controls:
-  provider: openai
-  model: openai/gpt-4.1-mini
-  thinking: low
-  append_system_prompt: |
-    Convert messy user reports into concise reproduction steps, affected surfaces,
-    suspected owners, and the next question that would unblock diagnosis.
+```
+<!-- .agents/agents/platform-operator/agent.md -->
+---
+name: platform-operator
+description: Higher-reasoning role for infrastructure, incidents, CI, and release safety.
+---
+
+Treat production-like systems as high-risk. Prefer diagnosis before mutation,
+name rollback paths, and ask before deploys, credential use, payments, or
+irreversible changes.
 ```
 
-```yaml
-# profiles/exec-briefing/profile.yml
-id: exec-briefing
-label: Executive Briefing
-description: Fast profile for dense status synthesis and decision memos.
-inherits:
-  - base-acme
-controls:
-  provider: openai
-  model: openai/gpt-4.1
-  thinking: medium
-  append_system_prompt: |
-    Produce dense prose for leaders: state the decision, evidence, risk, owner,
-    deadline, and the smallest reversible next action. Avoid implementation trivia unless it changes the decision.
+```
+<!-- .agents/agents/support-triage/agent.md -->
+---
+name: support-triage
+description: Lower-cost role for ticket summarization, reproduction notes, and routing.
+---
+
+Convert messy user reports into concise reproduction steps, affected surfaces,
+suspected owners, and the next question that would unblock diagnosis.
+```
+
+```
+<!-- .agents/agents/exec-briefing/agent.md -->
+---
+name: exec-briefing
+description: Fast role for dense status synthesis and decision memos.
+---
+
+Produce dense prose for leaders: state the decision, evidence, risk, owner,
+deadline, and the smallest reversible next action. Avoid implementation trivia
+unless it changes the decision.
 ```
 
 ## Budget annotation pattern
 
-Profiles can carry comments that explain why a role uses a given model and thinking level without embedding current vendor prices.
-Keep the metric relative, because token prices and model names drift.
+Agent `config.json` entries can carry comments-in-docs that explain why a role uses a given model and thinking level without embedding current vendor prices. Keep the metric relative, because token prices and model names drift:
 
-```yaml
-# Metric docstring for catalog maintainers:
-# budget_units estimates relative spend and latency for a role, not an invoice.
-# budget_units = expected_input_tokens * input_weight
-#              + expected_output_tokens * output_weight
-#              + expected_reasoning_tokens * thinking_weight
-# thinking_weight guideline: low=1, medium=2, high=4, xhigh=8.
-# Use low/medium for repeatable summarization or routing; use high/xhigh when a wrong answer
-# can cause rework, outages, bad code, unsafe operations, or expensive human review.
-
-# profiles/platform-operator/profile.yml excerpt
-controls:
-  model: anthropic/claude-opus-4
-  thinking: xhigh # Expensive by design: infra mistakes dominate token spend.
+```text
+budget_units estimates relative spend and latency for a role, not an invoice.
+budget_units = expected_input_tokens * input_weight
+             + expected_output_tokens * output_weight
+             + expected_reasoning_tokens * thinking_weight
+thinking_weight guideline: low=1, medium=2, high=4, xhigh=8.
+Use low/medium for repeatable summarization or routing; use high/xhigh when a
+wrong answer can cause rework, outages, bad code, unsafe operations, or
+expensive human review.
 ```
 
-This gives the organization a publishable catalog with clear defaults: cheaper profiles for high-volume low-risk work, stronger reasoning for code and infrastructure, and role prompts that teach the agent what evidence and output shape matter for each job.
+## Governance
+
+Because the catalog is a normal repository publishing normal files, organization changes flow through ordinary pull requests: a role prompt change is a reviewable diff to one `agent.md`. Consumers pin the catalog by SHA and bump deliberately; `outfitter dump` shows exactly what a pinned composition resolves to before an approval. Recurring org automation — like a `weekly-kpis` report — lives in the same repository as an agent run through [GitHub Actions](../actions.md); a dedicated task/bake contract for that work is a [separate upcoming RFC](../tasks.md).