@event4u/agent-config 2.18.0 → 2.20.0

package/docs/contracts/workflow-packs.md

@@ -0,0 +1,121 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# Workflow packs
+
+> **Status:** beta — first draft 2026-05-16 (Phase 2 Item 7 of
+> `step-15-product-refinement`).
+
+A **workflow pack** bundles a `(profile + preset + command-set +
+skill-allowlist)` combination into a single YAML so a user can adopt
+the full opinionated stance for their role without picking five
+independent settings.
+
+Packs do **not** introduce new commands, skills, or rules. They are
+a **composition contract** — every reference must resolve to an
+existing artefact that has already passed its own contract / linter
+gates.
+
+## Schema
+
+```yaml
+# .agent-src.uncompressed/packs/<pack-id>.yml
+pack:
+  id: <pack-id>                      # kebab-case, file name without .yml
+  audience:
+    label: "<human-readable>"
+    one_liner: "<= 120 chars, what the pack does for the user>"
+  composition:
+    profile_id: <profile.id>         # MUST exist in profiles/
+    preset_id: <preset.id>           # MUST exist in presets/
+  surface:
+    commands_allowed:                # ≤ 12 — slash-command names without leading slash
+      - <command>
+    skills_allowed:                  # ≤ 15 — skill IDs from skills-catalog
+      - <skill>
+    personas:                        # ≤ 4 — persona IDs from personas/
+      - <persona>
+  rationale:                         # why this combination, not free-form notes
+    why_this_profile: "<one paragraph>"
+    why_this_preset: "<one paragraph>"
+    why_these_commands: "<one paragraph>"
+```
+
+### Field semantics
+
+| Field | Type | Required | Notes |
+|---|---|:-:|---|
+| `pack.id` | string | yes | Matches file stem. No collision with `profile.id` or `preset.id`. |
+| `composition.profile_id` | string | yes | Override applied to the chain documented in [`profile-system`](profile-system.md). Pack-supplied id wins over `.agent-settings.yml` only when the user explicitly opts in via `/onboard --pack <id>`. |
+| `composition.preset_id` | string | yes | Override applied to the chain documented in [`config-presets`](config-presets.md). Same opt-in semantics. |
+| `surface.commands_allowed` | list[string] | yes | Cap = **12**. Items must appear in [`command-clusters`](command-clusters.md). The pack does **not** disable other commands — the cap is for the wizard's first-screen rendering, not enforcement. |
+| `surface.skills_allowed` | list[string] | yes | Cap = **15**. Items must appear in `docs/skills-catalog.md`. Same render-only semantics. |
+| `surface.personas` | list[string] | yes | Cap = **4**. Items must appear in `.agent-src.uncompressed/personas/`. |
+| `rationale.*` | string | yes | Forces every pack to justify its composition in plain prose; reviewed at PR time, not at runtime. |
+
+## Resolution chain
+
+Packs are an **opt-in layer above the profile + preset chain**. The
+loader at `scripts/config/packs.py` (Phase 2 deliverable — not yet
+shipped) reads the pack iff:
+
+1. `--pack <id>` flag passed to `/onboard` or `agent-config init`, **or**
+2. `pack.id` set in `.agent-settings.yml` (written by `/onboard --pack`).
+
+When a pack is active:
+
+- `composition.profile_id` is passed to `profiles.load()` as
+  `pack_profile_id` (already wired — see `scripts/config/profiles.py`).
+- `composition.preset_id` is passed to `presets.load()` analogously.
+- `surface.*` lists override the rendered command / skill lists in
+  `/onboard` and in the README "Six entry paths" surface **for the
+  duration of the active pack only**.
+
+Removing a pack (`/onboard --pack none`) reverts to the underlying
+profile + preset defaults; **no data is lost**.
+
+## Validation
+
+`scripts/lint_packs.py` (Phase 2 deliverable — not yet shipped) fails
+CI on:
+
+- Missing required field.
+- `profile_id` / `preset_id` / `commands_allowed` / `skills_allowed`
+  / `personas` referencing an artefact that does not exist.
+- Cap violation (commands > 12, skills > 15, personas > 4).
+- `pack.id` collision with another pack, profile, or preset id.
+
+Until the linter lands, packs are reviewed by hand at PR time against
+this schema.
+
+## What packs do **not** do
+
+- **Do not** declare new commands. Use [`command-clusters`](command-clusters.md).
+- **Do not** modify rules. Use the kernel-rule edit process.
+- **Do not** override safety floors. Domain-safety rules
+  (`.agent-src.uncompressed/rules/domain-safety-*.md`) apply
+  unconditionally — packs cannot widen the deny-list.
+- **Do not** ship telemetry or usage hints. Packs are pure composition.
+
+## Seed packs
+
+Three packs ship at Phase 2 Item 7 close:
+
+| Pack id | Profile | Preset | One-liner |
+|---|---|---|---|
+| `founder-mvp` | `founder` | `fast` | Ship the MVP and the pitch deck in the same week. |
+| `content-engine` | `content_creator` | `balanced` | Editorial calendar, brand voice, and ghostwriter on one loop. |
+| `agency-delivery` | `agency` | `strict` | Multi-client refine → estimate → deliver with audit-grade trace. |
+
+Each pack lives at `.agent-src.uncompressed/packs/<id>.yml` and is
+covered by the validation rules above.
+
+## See also
+
+- [`profile-system`](profile-system.md) — profile axis (audience defaults)
+- [`config-presets`](config-presets.md) — preset axis (risk appetite)
+- [`command-clusters`](command-clusters.md) — verb axis (invocation)
+- [`command-taxonomy`](command-taxonomy.md) — discoverability axis
+- `step-15-product-refinement` § Phase 2 Item 7

package/docs/decisions/ADR-010-profile-pack-preset-boundary.md

@@ -0,0 +1,132 @@
+---
+adr: 010
+status: proposed
+date: 2026-05-16
+decision: profile-pack-preset-boundary
+supersedes: —
+superseded_by: —
+phase: v2.x · step-15 Phase 1 prerequisite
+---
+
+# ADR-010 — Profile / Pack / Preset Boundary
+
+## Status
+
+**Proposed** · 2026-05-16 · pending Phase 1 of
+[`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md).
+Council v3 action #2 (`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`): <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+**"Profile / Pack / Preset boundary is undefined; Phase 2 will duplicate
+Phase 1 abstractions"**. Promoted from Phase 2 to Phase 1 prerequisite —
+the profile loader (Phase 1 item 1) cannot ship without the boundary.
+
+## Context
+
+Step-15 introduces three new configuration concepts:
+
+- **Profile** — Phase 1 item 1: `profile.id` ∈ {`founder`, `developer`,
+  `content_creator`, `agency`, `finance`, `ops`}.
+- **Preset** — Phase 1 item 4: `preset.id` ∈ {`fast`, `balanced`,
+  `strict`} bundling 12+ governance knobs (cost caps, confidence band,
+  block-on-risk, …).
+- **Pack** — Phase 2 item 7: workflow bundles (`founder-mvp`,
+  `content-engine`, `agency-delivery`) of `(profile + preset +
+  command-set + skill-allowlist)`.
+
+A pre-existing fourth concept is in play:
+
+- **`cost_profile`** — current setting in `.agent-settings.yml`, values
+  `minimal` / `balanced` / `full` / `custom`. Owns **rule-tier loading**
+  (kernel · kernel + tier-1 · kernel + tier-1 + tier-2). Contract:
+  [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md).
+
+Without a written boundary, three failure modes are predictable:
+
+1. The preset loader re-implements rule-tier gating (overlap with
+   `cost_profile`).
+2. Packs ship duplicate `profile` + `preset` defaults that drift from
+   the canonical source.
+3. Three teams add knobs to three places, and a user picking
+   `developer + strict + founder-mvp` discovers contradicting values
+   at runtime.
+
+## Decision
+
+Four orthogonal axes, four owners, one resolution chain.
+
+| Axis | Answers | Owns | Identity key |
+|---|---|---|---|
+| **Profile** | *Who is the user?* (audience taxonomy) | Default skill/command surface; README entry-paragraph; persona pre-selection | `profile.id` |
+| **Preset** | *How cautious is this run?* (risk + cost + autonomy budget) | The 12+ governance knobs (per-call $ ceiling, confidence band, block-on-risk, autonomy default, council escalation, …) | `preset.id` |
+| **Pack** | *What bundle of skills + commands?* (workflow recipe) | A frozen `(profile, preset, allow_skills, allow_commands)` 4-tuple; nothing more | `pack.id` |
+| **Cost Profile** | *How many rules load?* (token budget) | Rule-tier loading at session start (kernel · +tier-1 · +tier-2) | `cost_profile` |
+
+### Resolution chain (read order, last writer wins)
+
+```
+pack  →  profile  →  preset  →  cost_profile  →  user/env/runtime overrides
+```
+
+- A **pack** declares defaults for `profile`, `preset`, and the
+  skill / command allowlists. It cannot set `cost_profile` (that
+  axis belongs to the rule-tier loader and is governed separately).
+- A **profile** declares defaults for `preset`, audience-specific
+  README pointer, persona pre-selection. It cannot set any preset
+  knob directly — only `preset.id`.
+- A **preset** owns the 12+ knobs. No other axis writes them.
+- A **cost_profile** owns rule-tier loading. No other axis writes it.
+- The user's `.agent-settings.yml`, environment variables, and
+  runtime CLI flags override every axis above them.
+
+### Non-overlap rules (Iron Law)
+
+```
+A KNOB BELONGS TO EXACTLY ONE AXIS.
+DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
+```
+
+- A pack **may not** override a preset knob; it overrides `preset.id`.
+- A profile **may not** override a preset knob; it overrides `preset.id`.
+- A preset **may not** override `cost_profile`; the user does that.
+- The CI `task lint-config-schema` (added in Phase 1) hard-fails on a
+  pack/profile YAML that names any preset-owned knob.
+
+## Consequences
+
+### Positive
+
+- Phase 1 ships the profile loader against a fixed surface (`profile.id`
+  → audience + `preset.id` + persona). No 12-knob inheritance ambiguity.
+- Phase 1 item 4 (Config Presets) owns the knobs alone. The "Cost
+  Enforcement" section in [`config-presets.md`](../contracts/config-presets.md)
+  has a single home.
+- Phase 2 item 7 (Workflow Packs) is a 4-tuple, not a re-implementation
+  of profile + preset. Pack YAML stays under 30 lines.
+- `cost_profile` keeps its single-axis charter; this ADR explicitly
+  refuses to fold it into the preset layer.
+
+### Negative
+
+- One more concept on the install screen (`profile` + `preset` + `pack`
+  + `cost_profile` = four axes). Mitigated by: the wizard (Phase 1 item
+  2) only asks for **profile** + **stack** + **risk appetite** and
+  derives the rest. Packs are opt-in; `cost_profile` keeps its
+  `balanced` default.
+- A skill-allowlist conflict between a pack and a runtime CLI flag is
+  resolved by "runtime wins". Users on a pack who shadow-disable a
+  skill will not see it again until the override is removed.
+
+### Neutral
+
+- This ADR records the boundary; it does **not** specify the seed
+  values for any axis. Profile IDs live in
+  [`docs/contracts/profile-system.md`](../contracts/profile-system.md)
+  (Phase 1 item 1). Preset knobs live in
+  [`docs/contracts/config-presets.md`](../contracts/config-presets.md)
+  (Phase 1 item 4). Pack shape lives in `docs/contracts/workflow-packs.md`
+  (Phase 2 item 7).
+
+## See also
+
+- [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `cost_profile` contract this ADR explicitly does **not** touch.
+- [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 items 1, 4 and Phase 2 item 7.
+- [`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/council-responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->

package/docs/decisions/INDEX.md

@@ -13,6 +13,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-007](ADR-007-agent-discovery-scopes.md) | Global Default Install With Export Subcommand | accepted | 2026-05-12 | — |
 | [ADR-008](ADR-008-installed-tools-manifest.md) | Committed Installed Tools Manifest Separate From Settings | proposed | 2026-05-12 | — |
 | [ADR-009](ADR-009-event4u-namespace.md) | Event4U Namespace And Claude Desktop Zip Bundles | accepted | 2026-05-13 | — |
+| [ADR-010](ADR-010-profile-pack-preset-boundary.md) | Profile Pack Preset Boundary | proposed | 2026-05-16 | — |
 
 ## Unnumbered (legacy)
 

package/docs/featured-commands.md

@@ -0,0 +1,27 @@
+# Featured Commands
+
+A curated subset of the 124 active commands. Full set lives in
+[`.agent-src/commands/`](../.agent-src/commands/) — see also
+[`docs/catalog.md`](catalog.md) for the complete index.
+
+## For developers
+
+| Command | What it does |
+|---|---|
+| [`/implement-ticket`](../.agent-src/commands/implement-ticket.md) | Drive a Jira / Linear ticket end-to-end through refine → plan → implement → test → verify |
+| [`/work`](../.agent-src/commands/work.md) | Same end-to-end loop for a free-form prompt — confidence-band gated |
+| [`/fix ci`](../.agent-src/commands/fix.md) | Fetch CI failures from GitHub Actions and fix them |
+| [`/review-changes`](../.agent-src/commands/review-changes.md) | Self-review local changes before creating a PR (five judges) |
+| [`/create-pr`](../.agent-src/commands/create-pr.md) | Create a GitHub PR with Jira-linked description |
+
+## For everyone
+
+| Command | What it does |
+|---|---|
+| [`/research`](../.agent-src/commands/research.md) | Survey / benchmark / competitive scan scaffolder — picks objects, defines fields |
+| [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) | Shape a fuzzy product ask into a refined backlog item — problem framing, AC tightening |
+| [`/ghostwriter:write`](../.agent-src/commands/ghostwriter/write.md) | Draft in a public-figure voice profile (mandatory disclosure footer) |
+| [`/challenge-me`](../.agent-src/commands/challenge-me.md) | Interactive grill-style interview that sharpens a fuzzy plan into a copyable pitch |
+| [`/fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) | Shape a capital-raise pitch — why-now / why-us / why-this framing |
+
+→ [Browse all 124 active commands](../.agent-src/commands/)

package/docs/parity/bench-ruflo.json

@@ -0,0 +1,58 @@
+{
+  "schema": "parity-bench-ruflo-v1",
+  "status": "infrastructure_ready_awaiting_corpus_run",
+  "owner_roadmap": "agents/roadmaps/step-11-ruflo-parity.md",
+  "parity_doc": "docs/parity/ruflo.md",
+  "parent_bench": "docs/parity/bench.json",
+  "claim_under_test": {
+    "source": "agents/audit-2026-05-14-north-star/external-findings.md § 2",
+    "headline": "Average dollar cost per 25-prompt corpus run, separated by model tier (Haiku / Sonnet / Opus) and by token class (input / output / cache-read / cache-write).",
+    "comparison_target": "ruflo cost-tracker README (claimed upstream, not yet pulled into this repo)",
+    "type": "claimed_upstream_not_verified_in_repo"
+  },
+  "measurement_protocol": {
+    "corpus": "bench/corpus/* (25-prompt corpus owned by step-4-measurement-and-benchmark.md)",
+    "tracker": "scripts/cost/track.mjs",
+    "pricing": "bench/pricing.yaml",
+    "session_source": "~/.claude/projects/*/sessions/*.jsonl (Claude Code-native, no manual tracking)",
+    "tokens_to_dollars": "track.mjs multiplies input/output/cache-read/cache-write tokens by per-1M pricing from bench/pricing.yaml, separated by model id",
+    "headline_output": "average dollar cost per 25-prompt run, with min / max / p50 / p90 across N reports"
+  },
+  "current_window": {
+    "report_count": 0,
+    "verdict": "awaiting_first_corpus_run",
+    "notes": "Phase 1-5 of step-11 delivered the cost-tracking and bench infrastructure. Phase 6 Step 2 awaits the first end-to-end 25-prompt corpus run against the live tracker. Until then this file exists as a methodology contract, not a verdict surface."
+  },
+  "soak_inheritance": {
+    "follows": "docs/parity/bench.json",
+    "min_days": 60,
+    "min_reports": 30,
+    "earliest_flip": "2026-07-15",
+    "arbiter_command": "task bench:baseline-ready",
+    "notes": "bench-ruflo.json flips status to 'baseline_ready' only after the parent bench.json flips. No independent soak window — same corpus, same arbiter."
+  },
+  "redundancy_verdict": {
+    "status": "pending",
+    "criterion": "Once bench.json soak completes, this verdict is set by comparing the dollar cost in current_window vs ruflo's published table.",
+    "outcome_branches": {
+      "redundant": "Our cost-per-25-prompt-run sits within Ruflo's published range (or beats it). G5 redundancy gate row for cost surface flips green.",
+      "behind": "Our cost-per-run > Ruflo's. Follow-up issue filed; G5 stays open."
+    }
+  },
+  "fields_pending_first_run": [
+    "current_window.avg_cost_per_run_usd",
+    "current_window.cost_by_model.haiku_usd",
+    "current_window.cost_by_model.sonnet_usd",
+    "current_window.cost_by_model.opus_usd",
+    "current_window.cost_by_class.input_usd",
+    "current_window.cost_by_class.output_usd",
+    "current_window.cost_by_class.cache_read_usd",
+    "current_window.cost_by_class.cache_write_usd"
+  ],
+  "decisions_pending": {},
+  "_meta": {
+    "created": "2026-05-16",
+    "created_by": "step-11-ruflo-parity.md Phase 6 Step 2",
+    "spec": "scripts/cost/track.mjs --bench-ruflo (planned wiring); for now the file is a methodology contract"
+  }
+}

package/docs/parity/bench.json

@@ -0,0 +1,41 @@
+{
+  "schema": "parity-bench-v1",
+  "status": "soak_in_progress",
+  "owner_roadmap": "agents/roadmaps/step-4-measurement-and-benchmark.md",
+  "contract": "docs/contracts/measurement-baseline.md",
+  "soak": {
+    "start_date": "2026-05-16",
+    "min_days": 60,
+    "min_reports": 30,
+    "earliest_flip": "2026-07-15",
+    "arbiter_command": "task bench:baseline-ready"
+  },
+  "current_window": {
+    "report_count": 1,
+    "days_elapsed": 0,
+    "verdict": "warmup",
+    "notes": "First infrastructure-shakedown run only. Numbers below are not the baseline."
+  },
+  "shakedown_run": {
+    "report": "bench/reports/2026-05-16T06-13-07Z-dev-projection.md",
+    "corpus": "dev",
+    "selection_accuracy_augment": 0.5,
+    "selection_accuracy_claude": 0.5,
+    "projection_fidelity_claude": 1.0,
+    "projection_fidelity_cursor": "not_applicable",
+    "projection_fidelity_cline": "not_applicable",
+    "projection_fidelity_windsurf": "not_applicable"
+  },
+  "decisions_pending": {
+    "compression_default": {
+      "kill_criterion": "docs/contracts/compression-default-kill-criterion.md",
+      "verdict": "deferred_until_baseline_closes",
+      "decision_owner": "step-4 closeout phase"
+    }
+  },
+  "downstream_consumers": [
+    "agents/roadmaps/step-99-north-star-restructure.md#G1",
+    "agents/roadmaps/step-2-skill-inventory-rationalization.md#G0",
+    "docs/contracts/compression-default-kill-criterion.md"
+  ]
+}

package/docs/parity/ruflo.md

@@ -0,0 +1,46 @@
+# Parity verdict — Ruflo
+
+> Per-row verdict against the eight Ruflo measurement-governance patterns
+> catalogued in
+> [`external-findings.md § 2`](../../agents/audit-2026-05-14-north-star/external-findings.md).
+> Owner roadmap: [`step-11-ruflo-parity.md`](../../agents/roadmaps/step-11-ruflo-parity.md)
+> (Phase 6 Step 1). Cross-index lives at
+> [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md)
+> Phase 5 Step 2.
+>
+> **Verdict legend:** `[x] covered by <file:line>` · `[~] superseded by <approach>` · `[!] gap`.
+> **Acceptance:** zero `[!]` rows. Closure flips the corresponding cell in the
+> [composite scorecard](../../agents/audit-2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
+> `vs Ruflo` column from `–` to `=` or `+`.
+
+**Measured-vs-claimed disclaimer:** Each row cites the **mechanism** that
+covers Ruflo's pattern. Numbers attached to those mechanisms (cost figures,
+smoke baselines, ADR count) are claimed until the 25-prompt bench corpus
+soak in [`bench.json`](bench.json) flips from `warmup` to `baseline_ready`
+(min 60 days, ≥ 30 reports — earliest 2026-07-15).
+
+## Verdict table
+
+| # | Ruflo pattern | Verdict | Evidence |
+|---|---|---|---|
+| 1 | **Cost-tracker plugin** — real model pricing, per-1M, separated input/output/cache | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) + [`bench/pricing.yaml`](../../bench/pricing.yaml) (Haiku/Sonnet/Opus per-1M, input/output/cache-read/cache-write split). Step-11 Phase 1. |
+| 2 | **Auto-capture from session jsonl** — reads Claude Code log, no manual tracking | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) reads `~/.claude/projects/*/sessions/*.jsonl` automatically. Step-11 Phase 1 Step 1. |
+| 3 | **50/75/90/100 % budget ladder with hard stop** | `[x] covered by` | [`scripts/cost/budget.mjs`](../../scripts/cost/budget.mjs) — exit codes 0/1/2/3 per tier; opt-in fail-closed via `cost.enforcement` setting. Fixtures: `tests/fixtures/cost/budget/{under-50,at-100,over-100}/`. Step-11 Phase 2. |
+| 4 | **Measured-vs-claimed disclaimer** — every percentage tagged "claimed upstream" | `[x] covered by` | One-line `**Measured-vs-claimed disclaimer:**` header block on all 9 active roadmaps in `agents/roadmaps/`. Verified 2026-05-16. Step-11 Phase 5 Step 4. |
+| 5 | **Smoke test as contract** — `bash scripts/smoke.sh` with declared baseline | `[x] covered by` | Four per-tier smoke scripts: [`scripts/smoke/kernel.sh`](../../scripts/smoke/kernel.sh), [`router.sh`](../../scripts/smoke/router.sh), [`schema.sh`](../../scripts/smoke/schema.sh), [`skills.sh`](../../scripts/smoke/skills.sh). Declared baselines in [`docs/contracts/smoke-contracts.md`](../contracts/smoke-contracts.md). CI gate: [`.github/workflows/smoke.yml`](../../.github/workflows/smoke.yml). Step-11 Phase 3. |
+| 6 | **Per-plugin ADR directory** — `docs/adrs/0001-*.md` co-located with subsystem | `[x] covered by` | Six bootstrap ADRs under [`docs/adrs/{cost,memory,router,schema,smoke,caveman}/`](../adrs/). Coverage gate: [`scripts/audit_adr_coverage.py`](../../scripts/audit_adr_coverage.py) (`task lint-adr-coverage`). Contract: [`docs/contracts/adr-layout.md`](../contracts/adr-layout.md). Step-11 Phase 4. |
+| 7 | **Namespace contract** — `<stem>-<intent>` kebab-case, reserved-names list | `[x] covered by` | [`scripts/lint_namespace.py`](../../scripts/lint_namespace.py) enforces shape + length floors + reserved-names + skill-dir-matches-name across 430 names · 0 issues. Contract: [`docs/contracts/namespace.md`](../contracts/namespace.md). CI gate: `task lint-namespace`. Step-11 Phase 5 Step 1. |
+| 8 | **Topology choices in swarm** — `hierarchical / mesh / star / adaptive` with anti-drift defaults | `[x] covered by` | [`.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md`](../../.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md) `Topology hints` subsection — 7-row table mapping each mode to topology + Ruflo anti-drift default (`hierarchical, 6–8 agents, raft consensus`). Step-11 Phase 5 Step 2. |
+| 9 | **MCP-tool count + source-line refs** — every tool with `<file>:<line>` citation | `[x] covered by` | [`docs/contracts/mcp-tool-inventory.md`](../contracts/mcp-tool-inventory.md) — 20 tools (9 stdio-implemented · 11 discovery stubs) each with catalog `<file>:<line>` + handler `<file>:<line>`. Generator: [`scripts/audit_mcp_tools.py`](../../scripts/audit_mcp_tools.py). CI drift gate: `task lint-mcp-inventory`. Step-11 Phase 5 Step 3. |
+
+## Open `[!]` rows
+
+**Zero.** Every Ruflo pattern is mechanism-covered. Numbers behind those
+mechanisms remain claimed until [`bench.json`](bench.json) soak completes
+(see disclaimer above).
+
+## Cross-references
+
+- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/audit-2026-05-14-north-star/external-findings.md)).
+- Bench-ruflo redundancy verdict: [`bench-ruflo.json`](bench-ruflo.json) (step-11 Phase 6 Step 2).
+- G5 redundancy gate cite: step-99 Acceptance Criteria row "G5 — external redundancy (Domination Mandate)".

package/docs/profiles.md

@@ -0,0 +1,91 @@
+# Six entry paths — by `profile.id`
+
+Each block below is the first-screen for one shipped profile. The
+`profile.id` written by `/onboard` selects the anchor; the block names
+the audience, the first three things the agent does for that role,
+and the exact commands and skills wired into the profile YAML at
+[`.agent-src.uncompressed/profiles/<id>.yml`](../.agent-src.uncompressed/profiles/).
+
+The summary table at the top of [`README.md`](../README.md) is the
+one-page index; the prose below is the deep version.
+
+<a id="profile-developer"></a>
+## 👩‍💻 `developer` — IC engineer
+
+Implement a ticket end-to-end, fix CI red, run a self-review before
+the PR. `/implement-ticket` refines the ticket, plans, edits, tests,
+and verifies; `/work` is the free-form sibling; `/review-changes`
+dispatches five judges (bug, security, tests, quality, architecture)
+on the local diff. Stack-aware skills cover Laravel · Symfony ·
+Next.js · React · Node. **Preset default: `balanced`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/developer.yml) ·
+[Role guide](getting-started-by-role.md#developer-the-original-audience).
+
+<a id="profile-content_creator"></a>
+## ✍️ `content_creator` — writers, ghostwriters, marketers
+
+Draft in someone else's voice, plan a quarter of content, ship a
+launch announcement. `/ghostwriter` fetches and writes against a
+public-figure voice profile; `/post-as` is the same primitive for
+your own voice (`.agent-user.md`); `voice-and-tone-design` and
+`messaging-architecture` lock the brand frame before any copy ships.
+**Preset default: `balanced`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/content_creator.yml) ·
+[Role guide](getting-started-by-role.md#creator-writer-marketer-indie-content-shop).
+
+<a id="profile-founder"></a>
+## 🚀 `founder` — solo / early-stage founder
+
+Sharpen a fuzzy idea, rank what to build, write the why-now slide.
+`/challenge-me` runs a grill-style interview that turns a vague plan
+into a copyable pitch; `/council` polls external AIs for a neutral
+second opinion; `rice-prioritization` ranks the backlog;
+`vision-articulation` and `fundraising-narrative` shape the
+internal-vs-external story. **Preset default: `fast`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/founder.yml) ·
+[Role guide](getting-started-by-role.md#founder-early-stage-operator-wearing-every-hat).
+
+<a id="profile-agency"></a>
+## 🏛 `agency` — multi-client delivery shop
+
+Refine a fuzzy client ask into an estimated, AC-tight ticket; turn a
+phase into a roadmap; ship per client without losing decision
+provenance. `/refine-ticket` rewrites the ticket and surfaces top-5
+risks; `estimate-ticket` sizes and splits; `decision-record` anchors
+the trade-off in an ADR before code starts. **Preset default:
+`strict`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/agency.yml) ·
+[Role guide](getting-started-by-role.md#consultant-advisory-freelance-fractional).
+
+<a id="profile-finance"></a>
+## 💼 `finance` — CFO / fractional finance / FP&A
+
+Build a DCF, stress-test the plan, frame the runway call. `dcf-modeling`
+walks the WACC / terminal-value / 5-year-hold reasoning; `forecasting`
+reconciles top-down vs bottom-up; `scenario-modeling` produces the
+base / upside / downside cuts; `runway-cognition` frames the
+fundraise-vs-cut-vs-grow decision. **Preset default: `strict`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/finance.yml) ·
+[Role guide](getting-started-by-role.md#finance--ops-cfo-controller-ops-lead-founder-finance).
+
+<a id="profile-ops"></a>
+## 🛡 `ops` — RevOps, support, SRE-adjacent
+
+Threat-model a change before it ships, command the incident when it
+breaks, build the dashboard that catches it next time.
+`/threat-model` enumerates abuse cases and trust boundaries before
+the first line of code; `incident-commander` frames severity and
+post-mortem; `dashboard-design` chooses the right RED / USE / Golden
+Signal panel. **Preset default: `strict`.**
+[Profile YAML](../.agent-src.uncompressed/profiles/ops.yml) ·
+[Role guide](getting-started-by-role.md#finance--ops-cfo-controller-ops-lead-founder-finance).
+
+> **Universal AI Agent OS, not "for developers only".** The same
+> orchestration core also drives non-software trades. Worked-example
+> user types ship for [galabau](../.agent-src.uncompressed/user-types/galabau-field-crew.md),
+> [metalworking](../.agent-src.uncompressed/user-types/metalworking-shop.md),
+> [truck driving](../.agent-src.uncompressed/user-types/truck-driver.md) —
+> with a [scaffold](../.agent-src.uncompressed/user-types/_template/) for
+> contributing your own.
+
+→ [Public catalog](catalog.md) (all rules, skills, commands, guidelines) · [Skills only](skills-catalog.md) · [llms.txt](../llms.txt)

package/docs/recruits/_template.md

@@ -0,0 +1,81 @@
+# Recruit — `<short-handle>`
+
+> **step-13 Phase 1 intake template.** One file per recruit. Filename:
+> `<YYYY-MM-DD>-<source>-<handle>.md` (e.g. `2026-05-20-indiehackers-jsmith.md`).
+> The maintainer fills this in **before** the recruit's first session; the
+> session-log section gets appended live during the walkthrough.
+
+## Identity & source
+
+- **Handle / display name:** `<as-they-want-to-be-credited>`
+- **Source channel:** (indie-hackers | r/ContentWritingJobs | product-hunt | direct-dm | other)
+- **First contact:** YYYY-MM-DD via `<thread-url-or-DM-context>`
+- **Role / self-description:** `<one-line, in their words>`
+- **User-type fit:** (consultant | creator | founder | finance | ops | gtm | other)
+- **Tool host they already use:** (claude-desktop | claude-code | cursor | windsurf | copilot | chatgpt-web | none)
+
+## Consent
+
+- **Attribution:** (full-name-OK | first-name-OK | role-only | fully-anonymous)
+- **Screenshot publication:** (yes | yes-with-redaction | no)
+- **Verbatim quote publication:** (yes | yes-with-review | no)
+- **Case-study publication if outcome lands:** (yes | maybe-revisit | no)
+- **Consent record:** `<link-to-dm-or-email-thread-or-signed-form>`
+
+> Consent gate per step-13 Phase 1 row 3 — a recruit without an explicit
+> consent record cannot anchor `agents/eval-findings/`. Anonymised
+> finding is acceptable; missing consent record is not.
+
+## Pre-session readiness
+
+- [ ] Recruit has Claude Desktop installed *(or equivalent MCP host)*
+- [ ] Recruit has a real task ready to bring to the session
+- [ ] Maintainer has [`docs/mcp-server.md`](../mcp-server.md) open in another tab
+- [ ] Maintainer has stopwatch / screen-recording ready for the install-time
+  measurement (Phase 1 row 2 — `< 10 minutes` gate)
+
+## Session log
+
+Append-only during the walkthrough. Timestamp every observation;
+"silent" minutes are also a signal.
+
+```
+HH:MM  start — recruit shares screen, opens Claude Desktop
+HH:MM  install step 1 (`task mcp:setup`): outcome / friction / quote
+HH:MM  install step 2 (Claude Desktop config paste): outcome / friction / quote
+HH:MM  first invocation attempt: prompt / which skill fired / verdict
+...
+HH:MM  end — total install time: __ min __ s
+```
+
+## Friction inventory
+
+At least **two** real friction points (per step-12 Phase 7 L130 spirit).
+Empty list = the session wasn't real.
+
+1. <where they stalled, in their words> → <what we fixed / parked>
+2. <...>
+
+## Outcome verdict
+
+- **MCP setup time:** `__ minutes __ seconds` (gate: `< 10 min`)
+- **First useful invocation reached without terminal?:** (yes | no | partial)
+- **Recruit would recommend to a peer?:** (yes | maybe | no | declined-to-answer)
+- **Eligible to anchor `agents/eval-findings/`?:** (yes | no — reason)
+
+## Cross-links
+
+- **Eval-finding file (if logged):** `agents/eval-findings/YYYY-MM-DD-<slug>.md`
+- **Case-study file (if subject opted in):** `docs/case-studies/YYYY-MM-DD-<type>-<slug>.md`
+- **Roadmap rows closed by this session:**
+  - step-13 P1 row 1 (recruit) — yes / no
+  - step-13 P1 row 2 (`< 10 min` gate) — yes / no
+  - step-13 P1 row 3 (consent record) — yes / no
+
+## Maintainer follow-up
+
+- [ ] Eval-finding committed
+- [ ] Recruit thanked + sent the published finding link
+- [ ] Skill-description deltas filed *(any friction that maps to a
+  skill description widening or a missing trigger phrase)*
+- [ ] Case-study slot offered *(if outcome was useful + consent allows)*

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.18.0",
+    "version": "2.20.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,