feat(outfitter skill): proactive agentic-design advisor

.outfitter/skills/outfitter/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: outfitter
-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.
+description: Outfitter's always-on advisor. Explain Outfitter and compose/inspect/maintain .agents resources, agents and their loadouts, personas, skills, and settings — and, proactively, recognize which agentic-design patterns fit the user's project and apply them with Outfitter's primitives, so the user need not be an expert in agentic design. Use when a user asks about Outfitter itself (the .agents protocol, profiles, personas, catalogs, skills, settings, launches) or asks to set up/change/debug/migrate a launch; also engage proactively while composing agents, CI, or deployments, and when asked to audit a project for agentic-pattern opportunities.
 
 # TODO: once directory reference materialization lands, collapse the list
 # below to a single `- file: docs/documentation` entry so the whole
@@ -30,14 +30,27 @@ references:
   - file: docs/documentation/migration.md
   - file: docs/documentation/first-time-cli-agent-users.md
   - file: docs/documentation/iterating-on-profiles.md
+  - file: docs/documentation/conventions.md
+  - file: docs/documentation/recurring-runs.md
+  - file: docs/documentation/in-cluster.md
+  - file: docs/documentation/channels.md
+  - file: docs/documentation/usecases/organization-profile-catalog.md
 ---
 
 # Outfitter
 
-Use this skill to answer questions about Outfitter and to guide changes to
-`.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.
+Use this skill to answer questions about Outfitter, to make changes to `.agents`
+resources and launches, and — proactively — to recognize when an agentic-design
+**pattern** fits the user's project and offer to apply it. The user should not have
+to be an expert in agentic design: that expertise lives in these references, and
+your job is to bring the right pattern to their situation. Classify the request,
+read only the relevant reference, and follow its cross-references before answering
+or editing configuration.
+
+Be proactive but not noisy: when a project signal in **Agentic patterns** appears
+while you work — or when the user asks for help without a specific request, or asks
+you to **audit** their project — surface the fitting pattern and offer to apply it.
+Suggest the one or two highest-value patterns, not every possibility.
 
 ## Routing
 
@@ -69,6 +82,16 @@ before answering or editing configuration.
 - 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`.
+- Recurring or scheduled work, and the local-loop → Actions-cron → cluster
+  graduation ladder: read `references/recurring-runs.md`.
+- Running agents in Kubernetes — resident, CronJob, or subagent Jobs via the
+  operator: read `references/in-cluster.md`.
+- Channel intake (email, Signal, GitHub notifications) that wakes an agent on new
+  work: read `references/channels.md`.
+- Ambient, always-true rules and "place once, specialize downward": read
+  `references/conventions.md`.
+- An organization adopting Outfitter — a control catalog and shared defaults: read
+  `references/usecases/organization-profile-catalog.md`.
 - Getting hooks working per harness: read `references/hooks.md`.
 - Migrating from another agent CLI setup: read
   `references/switching-to-outfitter.md`.
@@ -87,6 +110,52 @@ before answering or editing configuration.
 
 `references/README.md` is the documentation index if no entry above fits.
 
+## Agentic patterns
+
+Watch for these project signals. When one appears, name the fitting pattern, read
+its reference, then propose the concrete change and offer to apply it (see
+*Applying changes*). Bring the pattern to the user — don't require them to know it.
+
+- **Repo receives issues or PRs** → a headless CI agent that triages, labels, and
+  comments (`actions-agent` + an `issue-triage`-style skill). Reference:
+  `references/actions.md`. Apply: scaffold the workflow and the agent.
+- **"Every N", "nightly", "watch", a recurring chore** → the graduation ladder:
+  local loop → Actions cron → in-cluster CronJob/resident. Reference:
+  `references/recurring-runs.md`. Apply: pick the surface matching how often and
+  where it must run; the composition stays the same, only the trigger changes.
+- **Inbound messages — email, Signal, GitHub notifications** → channel intake: the
+  `channels` extension wakes the agent, paired with a channel skill. Reference:
+  `references/channels.md`.
+- **Always-on or cluster-local access** → an in-cluster resident agent with Secrets
+  and quota. Reference: `references/in-cluster.md`. Apply: compose an
+  `Organization` + `Agent`.
+- **One agent per task, or a profile carrying every capability** → few agents, many
+  skills; make broad skills routers. References: `references/best-practices.md`,
+  `references/skills.md`. Apply: split capabilities into skills selected by loadout.
+- **Cross-context, parallelizable, or review work** → subagent delegation (a leader
+  with bounded delegates). Reference: `references/subagents.md`.
+- **A rule that should always hold — commit style, secret hygiene** → author it once
+  in the tree's shared `agents.md` and inherit down; never paste it per-agent or
+  make it a skill. Reference: `references/conventions.md`.
+- **An organization adopting Outfitter** → an `owner/.outfitter` control catalog
+  with shared conventions and pinned revisions. References:
+  `references/usecases/organization-profile-catalog.md`, `references/catalogs.md`.
+
+## Audit a project
+
+When the user asks you to audit their project — or asks for help without a specific
+request — do a quick pass and surface the highest-value opportunities:
+
+1. **Survey signals:** repo type and languages; existing `.agents` (agents, skills,
+   settings); CI workflows (`.github/workflows`); Kubernetes manifests; credentials
+   or channel configuration; and the user's stated goal.
+2. **Match** them against *Agentic patterns* above.
+3. **Present a prioritized shortlist** — the two or three highest-value patterns,
+   not every match — each as: the opportunity, the pattern, and the concrete change
+   you would make.
+4. **Offer to apply** the top one, and apply it per *Applying changes* on
+   confirmation.
+
 ## Working on Outfitter configuration
 
 1. Inspect the current configuration before editing:
@@ -103,14 +172,26 @@ before answering or editing configuration.
 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 validate --strict` and, when possible, a
-   smoke test such as `outfitter run <agent-id> -- --help`.
+4. Apply patterns end to end — don't stop at describing them:
+   - **Compose:** write/edit the `.agents` resources directly (agents, skills,
+     loadouts, shared `agents.md`) — what `outfitter` governs.
+   - **CI:** scaffold the workflow and open it with `gh` (`references/actions.md`).
+   - **In-cluster:** apply the `Organization`/`Agent` custom resources with
+     `kubectl` (`references/in-cluster.md`).
+   - **Catalog:** pin a revision or open a catalog PR (`references/catalogs.md`).
+5. Validate before applying: `outfitter validate --strict`, and when possible a
+   dry `outfitter dump --out <dir>` or `outfitter run <agent-id> -- --help` smoke
+   test.
+6. **Confirm before any outward or irreversible action** — opening a PR, pushing,
+   applying cluster resources, or anything that leaves the local workspace. State
+   exactly what you will run, then act only on approval.
 
 ## Default behavior
 
 If the user asks for help with Outfitter without a specific request:
 
 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.
+3. Offer to **audit the project** for agentic-pattern opportunities (see *Audit a
+   project*), or to compose or change an agent — reading `references/profiles.md`
+   and `references/agents.md` before editing.

README.md

@@ -1,10 +1,34 @@
 # Outfitter
 
-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.
+Outfitter is the toolchain for the [Dotagents `.agents` protocol](./docs/documentation/concepts.md): it resolves agent configuration from local and remote `.agents` trees, composes agents, skills, and knowledge by slug, and launches the result through wrapped agent CLIs like [`pi`](https://github.com/earendil-works/pi-coding-agent) and Claude Code.
 
 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.
 
-> **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.
+> These docs are the authoritative description of the `.agents` model Outfitter implements — start with [Concepts](./docs/documentation/concepts.md). For interchange, Outfitter pins draft protocol revision `502a9d5` of the referenced [external protocol site](https://dotagentsprotocol.com/). Implementation is rolling out across releases — a published CLI may lag these docs; [Migration](./docs/documentation/migration.md) covers the legacy profile format. For the design history, see [RFC #165](https://github.com/ai-outfitter/outfitter/issues/165).
+
+## Why
+
+Your agent setup is configuration: prompts, skills, MCP servers, model choices, permissions. Left alone it lives per tool and per laptop, gets pasted between repos, and drifts. Outfitter treats it like the rest of your infrastructure — layered, composed by slug, pinned by SHA, reviewed through pull requests.
+
+That turns one person's improvement into everyone's default. On Monday a platform engineer writes a `grafana-alert-investigate` skill in their own `~/.agents` tree and uses it at their desk. By Friday it is merged into the org catalog, pinned by version, and selected by slug from an agent that also runs on a CI schedule and in the cluster. Nobody else configured anything — their next run composes the new skill, and it costs their context window one line of routing metadata until it activates.
+
+Two ideas carry most of that leverage:
+
+- **The ladder.** Resources start personal and graduate upward — and every layer below inherits them back:
+
+  ```mermaid
+  flowchart LR
+    personal["~/.agents<br/>(you)"] -->|port up| project["project/.agents<br/>(your repo)"]
+    project -->|port up| org["org catalog<br/>(pinned by SHA)"]
+    org -->|contribute| community["community catalogs"]
+    community -. "inherited back, specialized downward" .-> personal
+  ```
+
+  ID-addressed resources — agents, skills, knowledge — override by ID across layers, and root shared context is selected by layer precedence, so you author a rule or skill once at the most general layer where it holds and specialize downward — never copy. See [Conventions](./docs/documentation/conventions.md).
+
+- **The surfaces.** The same composition runs everywhere work happens: interactively at your desk, [in GitHub Actions](./docs/documentation/actions.md) on any trigger, as [recurring loops](./docs/documentation/recurring-runs.md) — locally, on a CI cron, or on a cluster schedule — and as resident or job-based agents [in Kubernetes](./docs/documentation/in-cluster.md). Surface availability varies by release; each page notes its status.
+
+For the full argument, read the [Philosophy](./docs/philosophy.md).
 
 ## Quick start
 
@@ -64,30 +88,27 @@ Managed porting and persistent harness symlinks are deferred to
   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).
+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, across [four delegation boundaries](./docs/documentation/subagents.md#the-four-delegation-boundaries) from an in-session helper to a Kubernetes Job.
 
 ## Documentation
 
-- [Getting started](./docs/documentation/getting-started.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 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.
+The [documentation index](./docs/documentation/README.md) is organized as a journey — start personal, understand the model, grow across your org, automate more surfaces, contribute back:
+
+- **Start:** [Getting started](./docs/documentation/getting-started.md) · [First-time CLI agent users](./docs/documentation/first-time-cli-agent-users.md) · [Switching to Outfitter](./docs/documentation/switching-to-outfitter.md)
+- **Understand:** [Concepts](./docs/documentation/concepts.md) · [Agents](./docs/documentation/agents.md) · [Skills](./docs/documentation/skills.md) · [Personas](./docs/documentation/personas.md) · [Subagents and delegation](./docs/documentation/subagents.md)
+- **Grow:** [Catalogs](./docs/documentation/catalogs.md) · [Conventions](./docs/documentation/conventions.md) · [Organization catalog](./docs/documentation/usecases/organization-profile-catalog.md) · [Best practices](./docs/documentation/best-practices.md)
+- **Automate:** [GitHub Actions](./docs/documentation/actions.md) · [Recurring runs](./docs/documentation/recurring-runs.md) · [In-cluster agents](./docs/documentation/in-cluster.md) · [Hooks](./docs/documentation/hooks.md) · [State persistence](./docs/documentation/state.md)
+- **Reference:** [CLI](./docs/documentation/cli.md) · [Settings](./docs/documentation/settings.md) · [Adapter support matrix](./docs/documentation/support-matrix.md) · [Philosophy](./docs/philosophy.md)
+
+Use cases, story first:
+
+- [Shared conventions without duplication](./docs/documentation/usecases/shared-conventions.md) — one conventional-commits rule for every user, org, and project; zero copies.
+- [Flaky-test post-mortems in CI](./docs/documentation/usecases/flaky-test-postmortems.md) — an on-failure step that classifies flake vs. regression and comments with evidence.
+- [Grafana alert investigations in-cluster](./docs/documentation/usecases/grafana-alert-investigator.md) — a webhook turns each firing alert into one bounded investigation Job.
+- [Self-improving skills](./docs/documentation/usecases/self-improving-skills.md) — a weekly loop that proposes skill edits and ships only measured improvements.
+- [Persona reviews](./docs/documentation/usecases/persona-reviews.md) — customer personas your whole team can ask for feedback.
+- [Organization catalog](./docs/documentation/usecases/organization-profile-catalog.md) — shared org resources and defaults through a control repository.
+- [Engineering catalog](./docs/documentation/usecases/engineering.md) — engineering agents and skills for repeatable workflows.
 
 For local development, repository structure, and release workflow details, see [Contributing](./CONTRIBUTING.md).