@ai-outfitter/outfitter 1.4.0 → 1.6.0

package/docs/documentation/in-cluster.md

@@ -11,6 +11,8 @@ The Link Operator runs Outfitter-composed agents inside a Kubernetes cluster. Th
 
 The operator never interprets a profile, reads a secret's contents, or invokes the model — it provisions and starts; the agent layer does the rest.
 
+Because the operator does not look inside a Secret, the credentials a resident agent carries are the deployment's decision. A resident agent needs two forge tokens rather than one: the notification wake path accepts only a classic token, while its repository work should carry the narrowest credential available. [Give the agent a residence](../runbooks/give-the-agent-a-residence.md) is the procedure; [the forge credential model](../architecture/forge-credential-model.md) is the reasoning.
+
 ## Execution shapes
 
 | Shape                  | Kubernetes resource | Trigger                                                                                         |

package/docs/documentation/migration.md

@@ -21,7 +21,7 @@ This page is the manual migration reference, and the bundled Outfitter skill can
 | `<project>/.outfitter/local/settings.yml` (nested dir)  | `<project>/.agents/settings.local.yml` (flat, gitignored)                                                                                                                                        |
 | `profile_sources`                                       | `sources` supplying `.agents` payloads ([catalogs](./catalogs.md))                                                                                                                               |
 | `default_profile`                                       | `default_agent` naming an agent slug                                                                                                                                                             |
-| `outfitter run --profile <file-based id>`               | `outfitter run <agent-id>` (choose the harness with `--harness pi\|claude`)                                                                                                                      |
+| `outfitter run --profile <file-based id>`               | `outfitter run <agent-id>` (choose the harness with `--harness pi\|claude\|codex`)                                                                                                               |
 | `outfitter profile list` / `create` / `lint`            | `outfitter list agents` / author files directly / `outfitter validate`                                                                                                                           |
 | `profile_export` / `generated-system-prompt.md`         | `outfitter dump` ([Dump and bake](./dump-and-bake.md))                                                                                                                                           |
 | Free-form CI prompt + profile in `ai-outfitter/actions` | An agent run with structured inputs ([Actions](./actions.md)); the task/bake surface is a [future RFC](./tasks.md)                                                                               |

package/docs/documentation/personas.md

@@ -32,7 +32,7 @@ Neither tier is a resource Outfitter resolves; both are ordinary directories of
 
 ## Three ways to consume the same file
 
-- **Appended at launch**: `outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- …` — the direct run is the underlying interface, and the reviewer adopts the file as its identity for that session only. Pass `--append-prompt` rather than spelling the harness flag yourself after `--`: pi and Claude Code take append-prompt documents through different flags, so a hand-written passthrough only works on the harness it was written for, and fails silently on the other. An agent using the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill can drive the same run in the background or synchronously and capture its report in a durable file. See [Persona reviews](./usecases/persona-reviews.md) for the runnable form of both.
+- **Appended at launch**: `outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- …` — the direct run is the underlying interface, and the reviewer adopts the file as its identity for that session only. Pass `--append-prompt` rather than spelling the harness flag yourself after `--`: pi and Claude Code take append-prompt documents through different native flags. Codex has no native append flag yet, so its adapter warns that the document is dropped. An agent using the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill can drive the same run in the background or synchronously and capture its report in a durable file. See [Persona reviews](./usecases/persona-reviews.md) for the runnable form of both supported identity projections.
 - **Pasted into a web agent**: upload or paste the file unchanged into claude.ai project knowledge or a ChatGPT project as stakeholder context. Same artifact, zero conversion.
 - **Ordinary reading context**: any agent doing product planning, research, or writing can read the file to know who the work is for.
 

package/docs/documentation/settings.md

@@ -22,7 +22,7 @@ In a standalone `.agents` repository the repository root is the tree, so the fil
 ```yaml
 # .agents/settings.yml
 default_agent: engineer # which agent runs by default
-default_harness: pi # which harness to launch: pi or claude
+default_harness: pi # which harness to launch: pi, claude, or codex
 
 # Where protocol resources come from, beyond this tree and ~/.agents.
 sources:

package/docs/documentation/state.md

@@ -190,6 +190,33 @@ The last form is how a resident or in-cluster agent keeps continuity across rest
 
 ## Claude Code state paths
 
+Claude credentials need a narrow adapter bridge in addition to the path-keyed state below. Claude
+reads `.credentials.json` and `.claude.json` directly from `CLAUDE_CONFIG_DIR`; the ephemeral
+projection gives `.credentials.json` no durable home, and `.claude.json`'s native location
+(`~/.claude.json`, outside `~/.claude`) does not share its config-dir-relative path. Outfitter
+seeds `.credentials.json` before launch. It seeds `oauthAccount` and `hasCompletedOnboarding` when
+those keys exist in durable state. It also seeds the current working directory's accepted-trust bit
+only when that exact trust decision already exists in durable state. Afterward it copies back the
+whole `.credentials.json` when changed and atomically merges `oauthAccount`. If the durable
+credentials also changed after seeding, Outfitter preserves that concurrent refresh and warns
+instead of copying the projected credentials back. Claude MCP OAuth tokens
+live under `mcpOAuth` in `.credentials.json`, keyed by `<serverName>|<hash>`, so server
+authorizations acquired in an Outfitter-launched Claude session persist across runs through that
+whole-file copy-back. Outfitter never copies the full machine-local `~/.claude.json` into a
+projection or merges its other projected state back. Trust accepted inside an Outfitter session is
+therefore discarded, so Claude prompts for trust on every run in a workspace that was never trusted
+natively.
+
+Claude session history has a second narrow bridge because `CLAUDE_CONFIG_DIR` also redirects
+Claude's native `projects/` tree into the temporary projection. Before launch, Outfitter derives
+Claude's project slug from the absolute working directory and copies only that slug directory from
+`~/.claude/projects/`. This keeps other projects' transcripts out of the projection while making
+`claude --continue` and `claude --resume` see earlier native or Outfitter-launched sessions. After
+the run exits or throws, Outfitter merges every new or content-changed regular session file from
+the projection's slug directories back into `~/.claude/projects/` atomically with mode `0600`.
+Durable files are never deleted. A seed or copy-back failure emits a warning and does not replace
+Claude's exit code or error.
+
 The Claude Code adapter declares these paths:
 
 ```yaml

package/docs/documentation/support-matrix.md

@@ -1,6 +1,6 @@
 # Adapter support matrix
 
-What Outfitter can project per agent CLI. 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 and Codex CLI are supported with gaps.
 
 Status values:
 
@@ -12,35 +12,47 @@ When a composition requests something an adapter cannot project, Outfitter warns
 
 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     |
+| What Outfitter projects                                                  | Pi        | Claude Code | Codex CLI |
+| ------------------------------------------------------------------------ | --------- | ----------- | --------- |
+| Agent config directory                                                   | Supported | Supported   | Roadmap   |
+| Session directory                                                        | Supported | Supported   | Roadmap   |
+| Agent identity (`system-prompt.md`, `agents.md`, `agents/<id>/agent.md`) | Supported | Supported   | Roadmap   |
+| Subagents (`agents/<id>` as harness delegates)                           | Supported | Supported   | Roadmap   |
+| Skills (`skills/<id>`)                                                   | Supported | Partial     | Roadmap   |
+| Commands (`commands/`)                                                   | Supported | Partial     | Roadmap   |
+| Knowledge (`knowledge/`)                                                 | Supported | Partial     | Roadmap   |
+| Model selection (`models.json`)                                          | Supported | Partial     | Partial   |
+| MCP servers (`mcp.json`)                                                 | Supported | Supported   | Partial   |
+| Extensions (agent `extensions:` loadout)                                 | Supported | Roadmap     | Roadmap   |
+| Plugins (agent `plugins:` loadout)                                       | Supported | Roadmap     | Roadmap   |
+| Credentials and environment                                              | Supported | Supported   | Roadmap   |
+| DeepWork job selection                                                   | Supported | Roadmap     | Roadmap   |
+| Hooks                                                                    | Partial   | Partial     | Roadmap   |
+| Tool availability (agent `tools:` loadout)                               | Supported | Supported   | Roadmap   |
+| Theme / UI presentation                                                  | Roadmap   | Roadmap     | Roadmap   |
+| Working directory                                                        | Roadmap   | Roadmap     | Roadmap   |
+| Pass-through arguments                                                   | Supported | Supported   | Supported |
+| Bootstrap hook                                                           | Supported | Roadmap     | Roadmap   |
+
+## Codex CLI notes
+
+- **Launch mode** — Outfitter launches `codex` directly. Pass-through arguments choose the native mode: no subcommand keeps the interactive CLI shape, while `-- exec ...` selects non-interactive `codex exec`.
+- **Agent identity and appended prompts** — Codex has no native identity projection yet: launches drop the composed identity/system prompt and any `--append-prompt` documents, supplied documents produce a separate warning, and `--strict` aborts before execution.
+- **Model selection (Partial)** — an agent's model maps to `-m`. Provider maps have no projection element and produce no warning. Thinking, tools, skills, subagents, extensions, plugins, and prompt templates remain unsupported and warn when selected.
+- **MCP servers (Partial)** — selected stdio fields (`command`, `args`, `env`, `cwd`) and streamable HTTP fields (`url`, `headers`) become repeated TOML-valued `-c mcp_servers.<id>.<key>=...` overrides. Server ids must contain only letters, digits, `_`, or `-`; other ids cannot be expressed by Codex `-c` key paths and are skipped with a warning. Legacy SSE and other HTTP transport types are also skipped with a warning. User and project `config.toml` servers remain active because Codex has no strict MCP isolation mode, so every launch warns that projection is additive, even when no servers are selected.
+- **Stdio environment safety** — `${ENV_NAME}` becomes an `env_vars` reference only when the stdio `env` key is also `ENV_NAME`; a reference that would rename the variable is dropped with a warning. Literal values pass through `env` and are visible in process arguments.
+- **HTTP header safety** — `${ENV_NAME}` becomes an `env_http_headers` reference, while `Authorization: Bearer ${ENV_NAME}` becomes `bearer_token_env_var`. Other header values pass through `http_headers` and are visible in process arguments. Outfitter warns for every literal stdio environment or HTTP header entry exposed in argv, so use environment references for secrets.
 
 ## Claude Code notes
 
-- **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.
+- **Config and session state** — Outfitter points `CLAUDE_CONFIG_DIR` at the baked composition. Before launch it copies only the current working directory's history from `~/.claude/projects/<project-slug>/` into the projection, so native `--continue` and `--resume` work without exposing other projects. After every successful or failed launch it atomically merges new or changed session files from every projected slug back into `~/.claude/projects/` with mode `0600`, never deleting durable history. Session bridge failures warn without masking the Claude exit. Outfitter also 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. MCP configuration from that port is no longer auto-discovered by Outfitter-launched Claude runs; those servers apply only when an agent selects them by slug. See the next bullet.
+- **Credentials, onboarding, and workspace trust** — before launch, Outfitter copies `~/.claude/.credentials.json` to the temporary root as `.credentials.json` with mode `0600`. The projected `.claude.json` contains `oauthAccount` and `hasCompletedOnboarding` when those keys are present in durable `~/.claude.json`. It also contains `projects[<cwd>].hasTrustDialogAccepted: true` only when that exact accepted trust decision already exists there; other projects and unrelated machine state are not copied. After any successful or failed launch, a `.credentials.json` changed by the run is copied back wholesale and `oauthAccount` is atomically merged into durable `.claude.json` without replacing unrelated keys. If the durable credentials also changed after seeding, Outfitter preserves that concurrent refresh and warns instead of copying back. MCP OAuth tokens live under `mcpOAuth` in `.credentials.json`, keyed by `<serverName>|<hash>`, so authorizations acquired in an Outfitter-launched Claude session persist across runs. Other projected `.claude.json` state, including trust accepted during the session, is discarded; a workspace that has never been trusted by native Claude therefore prompts again on every run.
+- **MCP servers** — every Claude launch passes the generated `mcp.json` through `--mcp-config` with `--strict-mcp-config`. MCP servers from user or project configuration, `.claude.json`, and plugins are therefore excluded; only servers selected by the composition are active.
 - **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).
+- **Tool availability** — `tools.allow` (after `tools.deny` removes entries) maps to both `--tools` (_availability_: an unlisted builtin is not in the session) and `--allowedTools` (_permission_: the granted tools are pre-approved, so a headless session is not stopped by a prompt); `tools.deny` always maps to `--disallowedTools`, including when both are declared, and a bare denied name removes the tool from context per Claude's docs. An allowlist that `tools.deny` empties maps to `--tools ""`, Claude's documented "disable all tools" form. Caveat: per the CLI reference, `--tools` governs the built-in set only — MCP tools (`mcp__server__*`) are unaffected and are governed by which MCP servers the loadout selects, so `--tools ""` is not exactly pi's zero-tool session when MCP servers are present. Claude's behavior here comes from `claude --help` and the CLI reference, not local measurement.
 - **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.
 
@@ -49,6 +61,7 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 - 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).
+- **Tool availability** — `tools.allow` (after `tools.deny` removes entries) maps to `--no-tools --tools a,b,c`, and `tools.deny` maps to `--exclude-tools a,b,c`. `--tools` is a hard allowlist across built-in, extension, and custom tools, so the session's tool set is exactly that list. An allowlist that `tools.deny` empties maps to `--no-tools` alone, a session with no tools at all. Note that `--no-builtin-tools` is deliberately not used: it keeps extension and custom tools enabled, so it does not express an empty tool set.
 - 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/usecases/org-onboarding-sdlc-report.md

@@ -0,0 +1,143 @@
+# Onboard an organization with an SDLC report
+
+A runbook for the first engineer who brings agentic engineering to their
+organization. The output is two artifacts: a baseline **SDLC report** that
+says where the org sits on the [adoption ramp](../../philosophy.md), and the
+org's **`.agents` repository** with that report as its first commit. The
+report's gaps become the backlog; the repository becomes the place the org's
+agent configuration lives from day one.
+
+Who runs this: an engineer with read access to the org's repositories. No
+org-wide rollout, approval, or infrastructure is required, and no agent
+session either — the scan is one command. The whole runbook is one person,
+one sitting, read-only until you create the repository.
+
+## 1. Prerequisites
+
+- `npx` (node 20.19+) or Docker.
+- An authenticated `gh` CLI with read access to the org.
+- Optional but valuable: your existing local checkouts of org repositories.
+  The scanner reads them in addition to the forge API — local working trees
+  show practice the forge cannot see, such as `.agents/` trees in progress
+  and instruction files that were never committed.
+
+## 2. Run the assessment
+
+[`@ai-outfitter/link`](https://github.com/ai-outfitter/link) audits the org
+against the catalog's governance baseline. Write the report straight into
+the dated directory it will be committed from:
+
+```sh
+npx @ai-outfitter/link@1 report <org> \
+  --out ~/repos/<org>/.agents/reports/sdlc/$(date +%F)-initial
+```
+
+Or with Docker, if you would rather not install anything:
+
+```sh
+docker run --rm -e GH_TOKEN="$(gh auth token)" -v "$PWD:/work" \
+  ghcr.io/ai-outfitter/link:1 report <org>
+```
+
+Add your local checkouts as sources to widen the evidence — a single repo, an
+owner folder of clones, or a whole `~/repos/` root:
+
+```sh
+npx @ai-outfitter/link@1 report <org> ~/repos/<org>
+```
+
+The scan is read-only: it lists repositories, reads git trees, and reads
+effective branch rules. It never clones and never writes to the forge. It
+samples at most the 30 most recently pushed repositories, and takes seconds
+rather than minutes.
+
+Naming a target scopes the report to it, so the file you are about to commit
+into `<org>`'s repository describes `<org>` and nothing else.
+
+You get one file, `report.json`, plus a copy in
+`$XDG_DATA_HOME/outfitter-link/`. It contains, for each repository, a
+maturity-ramp placement (level 0–5), the tree-derived signals behind it
+(instruction files, `.agents/` trees, agent workflows, deploy manifests), and
+a per-rule audit against the governance baseline. At org level it carries the
+milestones that gate each rung, the `gaps` blocking the next one, and
+`evidence_limits` — what the scan could not see, which bounds every claim in
+it.
+
+Read the `gaps` before moving on. They name what blocks the next rung, not
+the top of the ramp.
+
+To see the report rendered, with the workflow definitions beside it, clone
+the repository and run `link web`.
+
+### What the scan does not measure
+
+The scanner decides everything from file trees and branch rules, so it is
+fast, free, and reproducible — two runs of the same org agree apart from the
+`generated_at` and `scanned_at` timestamps, which is what makes report diffs
+a progress measure. The cost is that it reads no pull request history and
+makes no judgments: no cycle time, no rework rate, no inventory of which
+harnesses and model vendors are actually in use, and no duplication analysis
+across teams.
+
+When you want those, run the `sdlc-report` skill on a local coding harness as
+a second, deeper pass. It answers the same question with an agent's judgment
+instead of a checker's rules, and it emits recommendations. Start with
+`link` — it is the cheap, repeatable baseline, and it is the one you will
+re-run.
+
+## 3. Create the org `.agents` repository
+
+Create `<org>/.agents` on your forge and commit the report as its first
+content. Repository hygiene, learned the hard way:
+
+- The repository MUST NOT be public — private or internal visibility only.
+  The report is an honest map of your org's gaps. (This organization
+  publishes its own report deliberately, as a worked example. That is a
+  choice about a reference; it is not the default.)
+- If the repository already exists, commit only the report files. Leave any
+  uncommitted work in the checkout untouched, and if the default branch is
+  behind or checked out elsewhere, say so rather than silently moving it.
+
+```text
+<org>/.agents/
+  README.md                      # what this repo is; link to the report
+  reports/
+    sdlc/
+      YYYY-MM-DD-initial/
+        report.json
+```
+
+The initial report is the baseline: re-run the scan after each change (a
+quarterly cadence works, or after each rung climb) into a new dated
+directory, and the diff between reports is your progress measure — milestones
+met and rung movements, not anecdotes.
+
+This repository is also where the org's shared agent configuration grows: an
+`agents.md` with shared operating rules, role agents, skills, and a pinned
+`settings.yml`, following the [organization catalog](./organization-profile-catalog.md)
+conventions. Starting it with the report means the catalog's first commit
+explains _why_ the org is adopting agents and what it will measure — every
+later addition traces back to a gap in the baseline.
+
+## 4. Act on the report
+
+1. Take the first entry in `gaps` and automate that one workflow end to end —
+   for example, feature idea → reviewed PR ([Actions](../actions.md),
+   [in-cluster](../in-cluster.md)).
+2. Add the shared resources the org lacks, so the next team composes instead
+   of rebuilding. A repo whose `signals.catalog` is false is a candidate.
+3. Wire session-log capture into the automated workflow before merge. The
+   `session-capture` milestone is unmet in almost every first report, and it
+   stays unmeasurable until workflows upload session artifacts behind a
+   required check. Owning that record is what makes the next report richer,
+   and it is the raw material for evals and improvement
+   ([philosophy](../../philosophy.md)).
+4. Schedule the re-run ([recurring runs](../recurring-runs.md)) and commit
+   each new report beside the baseline.
+
+## Boundaries
+
+The scan is read-only; creating the `.agents` repository in step 3 is the
+runbook's first write, done by you deliberately. The report contains repo
+names, paths, and counts, never credentials or session content. Treat it as
+internal: it is an honest map of your org's gaps.

package/docs/documentation/usecases/persona-reviews.md

@@ -91,7 +91,7 @@ outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md --
   > docs/persona-reviews/platform-lead-onboarding.md
 ```
 
-This is the portable interface: it works from the project containing the persona, does not assume a particular catalog checkout path, and does not assume a harness — `--append-prompt` projects the document through whichever flag pi or Claude Code actually reads. Repeat it to compose an identity from several documents; see [When one file is not enough](../personas.md#when-one-file-is-not-enough). One shared agent adopts the file as its identity for that session only and writes a first-person, sourced report — evidence cited to the exact page or UI moment, assumptions labeled. The reviewer inherits the caller's configured model; reviews benefit from a strong reasoning model.
+This is the portable interface for pi and Claude Code: it works from the project containing the persona, does not assume a particular catalog checkout path, and projects `--append-prompt` through the native flag each harness reads. The Codex adapter has no native append flag and warns that the document is dropped. Repeat the option to compose an identity from several documents; see [When one file is not enough](../personas.md#when-one-file-is-not-enough). One shared agent adopts the file as its identity for that session only and writes a first-person, sourced report — evidence cited to the exact page or UI moment, assumptions labeled. The reviewer inherits the caller's configured model; reviews benefit from a strong reasoning model.
 
 ### Optional orchestration with the skill
 

package/docs/philosophy.md

@@ -2,6 +2,14 @@
 
 Make, share, and switch the agent profiles your coding agents use — manually or programmatically. A profile is just an agent and the loadout it composes; there is no separate profile format.
 
+## Trust through evidence
+
+An agent is trusted the same way a new teammate is: small scopes, reviewed work, and a paper trail. Outfitter treats all three as configuration. A profile bounds what an agent can do per environment — the planning agent that has write tools at your desk has none in the cluster. Adversarial review is a workflow step rather than a virtue, and workflows are built so that every transition writes to the record.
+
+## Own your session data
+
+The session record — what was asked, what the agent did, what it touched, what the review found — serves you as much as it serves the auditor. It answers "what happened and was it allowed" for an audit, and the same records are the inputs to evals, policy tuning, and eventually training. Organizations that let session data evaporate at the end of each run discard the asset that makes the whole system improvable. Store clean records first and decide on dashboards later — dashboards can always be built over clean records; records cannot be reconstructed from dashboards.
+
 ## Expeditious agents
 
 An agent is defined by its agency: its ability to make good decisions on the way to completing a task. Outfitter exists to make agents _expeditious_ — not just effective, but fast.
@@ -23,3 +31,15 @@ The same mechanism scales up a stair-step:
 - **Enterprises** publish and pin curated catalogs, keeping agent configuration reviewable, versioned, and consistent across the organization.
 
 At every level the goal is the same: the right profile, at the right moment, with nothing extra along for the ride.
+
+## The ramp to an autonomous lifecycle
+
+Outfitter's destination is a fully autonomous software development lifecycle: humans define goals and acceptance gates, agents own the middle. Nobody jumps there in one step. Adoption is a ramp with five rungs, and each Outfitter component targets a rung, so a user or an organization climbs without discarding the previous rung. This section is the canonical definition; the org README and the `sdlc-report` assessment skill compress or extend it.
+
+1. **Assisted** — autocomplete and chat; a human's hands stay on the keyboard.
+2. **Delegated** — a local agent does the task; the human defines the idea and reviews the PR.
+3. **Automated** — a workflow runs without a laptop: an issue, a message, or a schedule triggers agents in CI or a cluster, and adversarial review is part of the pipeline.
+4. **Governed** — the organization shares one pinned catalog of agents, skills, and policy; every agent action lands in an auditable record; resident agents work as onboarded teammates.
+5. **Self-improving** — the audit record feeds evals and model improvement; humans set goals and acceptance gates, agents own the middle.
+
+Two rules keep the climb honest. Never automate a workflow you have not first done manually — run it as an agent-assisted skill until you understand it, then promote it. And expand scope by moving the human locus of control outward one layer at a time: first the implementation, then the review, then the idea, until what remains human is the goal and the gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.",
   "type": "module",
   "repository": {

package/src/schemas/agent.schema.json

@@ -56,14 +56,20 @@
     "tools": {
       "type": "object",
       "properties": {
-        "allow": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-        "deny": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+        "allow": { "type": "array", "items": { "$ref": "#/$defs/toolName" } },
+        "deny": { "type": "array", "items": { "$ref": "#/$defs/toolName" } }
       },
       "additionalProperties": false
     }
   },
   "additionalProperties": true,
   "$defs": {
+    "toolName": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^\\s,-][^\\s,]*$",
+      "description": "A tool name. A leading '-' would become an independent harness flag when projected, and a comma or whitespace would split the name inside a projected flag value, so all three are rejected."
+    },
     "slugList": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 }

package/src/schemas/settings.schema.json

@@ -5,7 +5,7 @@
   "type": "object",
   "properties": {
     "default_agent": { "type": "string", "minLength": 1 },
-    "default_harness": { "enum": ["pi", "claude"] },
+    "default_harness": { "enum": ["pi", "claude", "codex"] },
     "cache_directory": { "type": "string", "minLength": 1 },
     "state_persistence": {
       "type": "object",

package/src/schemas/system-extension-hook.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://outfitter.dev/schemas/system-extension-hook.schema.json",
+  "title": "Outfitter system extension hook",
+  "type": "object",
+  "required": ["name", "harnesses"],
+  "properties": {
+    "name": { "type": "string", "minLength": 1 },
+    "harnesses": {
+      "type": "object",
+      "minProperties": 1,
+      "properties": {
+        "pi": { "$ref": "#/$defs/harnessHook" },
+        "claude": { "$ref": "#/$defs/harnessHook" },
+        "codex": { "$ref": "#/$defs/harnessHook" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "harnessHook": {
+      "type": "object",
+      "properties": {
+        "extensions": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^/" }
+        },
+        "env": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+          "additionalProperties": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}