@event4u/agent-config 9.8.0 → 9.9.0

package/docs/personas.md

@@ -1,178 +0,0 @@
-# Personas
-
-Personas are **review lenses** the host agent adopts when running a
-skill — not sub-agents, not execution modes. Each persona shapes
-*what* the agent looks for in a diff, plan, or artifact; the host
-identity, tools, and workflow stay the same.
-
-This page catalogs the **29 active personas** shipped with
-`event4u/agent-config` (5 core + 24 specialists), plus the 5
-**advisor** personas in `personas/advisors/`. It also explains how
-`personas:` (lens axis) interacts with `/mode` (role-mode axis).
-Removed personas are deleted in-commit (no soak window) — see
-[`persona-governance § Deprecation path`](../dist/agent-src/rules/persona-governance.md).
-
-## Catalog — Core (always-loaded, 5)
-
-| ID | Role | Wing | Owner | Lens summary |
-|---|---|---|---|---|
-| `developer` | Developer | — | package | Pragmatic implementer voice — what's the smallest correct change? |
-| `senior-engineer` | Senior Engineer | — | package | Long-horizon impact — what does this look like in 6 months? |
-| `stakeholder` | Stakeholder | — | package | Risk and politics — who owns the rollback if this fails? |
-| `critical-challenger` | Critical Challenger | — | package | Devil's-advocate voice — what assumption is load-bearing here? |
-| `ai-agent` | AI Agent | — | package | Tool-economy voice — token cost, prompt clarity, automation seam. |
-
-Note: `product-owner` was reclassified to **specialist** at v2.0 — see below.
-
-## Catalog — Specialists (opt-in, 24 active)
-
-| ID | Role | Wing | Owner | Lens summary |
-|---|---|---|---|---|
-| `qa` | QA | — | package | Test coverage and regression gates. |
-| `backend-architect` | Backend Architect | — | package | Service-layer boundaries, transaction scope, contract changes. |
-| `eloquent-tamer` | Eloquent Tamer | — | package | N+1, query shape, ORM idioms that melt the database. |
-| `performance-engineer` | Performance Engineer (`performance`) | — | package | Latency, allocations, hot-path cost, complexity class at 100× load. |
-| `data-integrity` | Data Integrity Reviewer (`data`) | — | package | Migration reversibility, lock behavior under live traffic, data-loss on backfill. |
-| `production-validator` | Production Validator | — | package | Last gate before done — no mock/stub remains; validated against real systems (ADR-098). |
-| `security-engineer` | Security Engineer | — | package | OWASP-shaped failure modes, secret leakage, trust boundaries. |
-| `frontend-engineer` | Frontend Engineer | — | package | Component lifecycle, reactive state, hydration boundaries. |
-| `product-owner` | Product Owner | — | package | Outcomes named, AC unfalsifiable, scope on record. |
-| `tech-writer` | Tech Writer | — | package | Release narratives, READMEs, AGENTS.md thin. |
-| `revops-maintainer` | RevOps Maintainer | — | package | Contributor lifecycle, package adoption funnel, release readiness. |
-| `discovery-lead` | Discovery Lead | — | package | Switch events, falsifiable hypotheses, theme ranking. |
-| `hollywood-director` | Hollywood Director (`ai-video`) | — | package | Live-action lens, lighting, blocking, negative constraints. |
-| `ai-video-technical-director` | AI Video Technical Director (`ai-video`) | — | package | Provider tuning — Veo / Kling / Sora / Higgsfield / OpenAI grammar. |
-| `brand-strategist` | Brand Strategist (`design`) | — | package | Positioning, archetype, voice, messaging; challenges weak briefs. |
-| `design-director` | Design Director (`design`) | — | package | Art-direction and brand-aligned visual judgment; composition, hierarchy, vector-vs-raster. |
-| `cmo` | CMO | 3 | package | Positioning anchored, messaging stacked, launches sequenced. |
-| `growth-pm` | Growth PM | 3 | package | Leaky-bucket vs growth-loop classified, activation correlated. |
-| `customer-success-lead` | Customer Success Lead | 3 | package | TTFV falsifiable, churn cause split, expansion pulled, NRR. |
-| `revops` | RevOps | 3 | package | Stage exit criteria, MEDDIC slots, forecast falsifiable. |
-| `engineering-manager` | Engineering Manager | 4 | package | 1:1 cadence, hiring loop, throughput-vs-morale tradeoff. |
-| `people-strategist` | People Strategist | 4 | package | Team shape, comp bands, ramp definitions, feedback craft. |
-| `finance-partner` | Finance Partner | 4 | package | Unit economics, runway, scenarios, the next 18 months. |
-| `strategist` | Strategist | 4 | package | Build-vs-buy, market entry, moat, vision, contracts, privacy. |
-
-## Per-domain count (persona-governance cap: max 2 specialists per domain)
-
-| Domain | Active specialists | Within cap |
-|---|---|---|
-| `ai-video` | `hollywood-director`, `ai-video-technical-director` | ✅ 2/2 |
-| `design` | `brand-strategist`, `design-director` | ✅ 2/2 |
-| GTM (Wing 3) | `cmo`, `growth-pm`, `customer-success-lead`, `revops` | ✅ (wing, not domain) |
-| Ops / Money (Wing 4) | `engineering-manager`, `people-strategist`, `finance-partner`, `strategist` | ✅ (wing, not domain) |
-| Backend | `backend-architect`, `eloquent-tamer` | ✅ 2/2 |
-| `performance` | `performance-engineer` | ✅ 1/2 |
-| `data` | `data-integrity` | ✅ 1/2 |
-
-Cross-cutting quality lenses (`qa`, `tech-writer`, `revops-maintainer`,
-`discovery-lead`, `production-validator`) are uncapped — they are not bound to a
-single content domain.
-
-Per-domain count is enforced by `src/scripts/lint_persona_governance.ts`
-(wired into `task ci`), which scans `src/agent-src/personas/` (the source of
-truth) and `src/skills/` + `src/rules/` for `personas:` citations.
-
-## Advisors (`personas/advisors/`, 5)
-
-Adversarial / second-opinion voices invoked by `ai-council` debates,
-not cited by skills directly:
-
-| ID | Lens |
-|---|---|
-| `contrarian` | Opposing the consensus position |
-| `executor` | Shipping bias — what's the minimum to land it? |
-| `expansionist` | Scope-widening — what else does this unlock? |
-| `first-principles` | Refuses analogy — derive from physics of the problem |
-| `outsider` | Naive reader — does this hold without prior context? |
-
-## Tier rules
-
-- **Core (≤ 6)** — always-loaded cast. 5 sections (Focus · Mindset · Unique Questions · Output Expectations · Anti-Patterns), ≤ 120 lines.
-- **Specialist** — opt-in lenses. 7 sections (Core-5 + Critical Rules + Workflows). Line cap is wing-scoped: ≤ 100 (no wing / Wings 1–2), ≤ 140 (Wings 3–4) per [`persona-schema § 4`](contracts/persona-schema.md).
-
-Schema contract: [`docs/contracts/persona-schema.md`](contracts/persona-schema.md). Governance rule: [`persona-governance`](../dist/agent-src/rules/persona-governance.md).
-
-## When to invoke a persona
-
-- **A skill cites it.** Skills declare `personas:` in frontmatter; the
-  agent adopts the listed personas while running the skill. No user
-  action needed. Example: `judge-security-auditor` cites
-  `security-engineer` — invoking the skill applies the lens.
-- **You want a second pass on existing work.** Pick the specialist
-  whose checklist matches the diff: `eloquent-tamer` for ORM heavy
-  changes, `frontend-engineer` for component changes,
-  `backend-architect` for service-seam changes.
-- **Adversarial review.** `critical-challenger` for the devil's-advocate
-  voice; `security-engineer` for abuse-case framing.
-
-Invocation example (when supported by the host tool):
-
-```text
---personas=backend-architect,security-engineer
-```
-
-The host agent reads the persona's `Critical Rules` and `Workflows`
-sections (specialist tier) or `Mindset` and `Unique Questions` (core
-tier) and merges them into its review pass.
-
-## `personas:` vs `/mode` — two different axes
-
-| Axis | What it controls | Example |
-|---|---|---|
-| `/mode` (role-mode) | Which **contract** the agent operates under for a turn — what outputs are mandatory, what work is refused | `/mode reviewer` refuses to write production code |
-| `personas:` (lens) | Which **review checklists** the agent overlays on a skill's procedure | `personas: [security-engineer]` adds OWASP-shaped checks to whatever skill is running |
-
-The two compose. `/mode reviewer` + `personas: [security-engineer,
-backend-architect]` = a review-only turn that applies both the
-security-abuse-case lens and the service-seam lens on top of the
-review contract.
-
-Personas are **not** a replacement for `/mode`. A persona cannot
-refuse work or change output contracts; that is `/mode`'s job.
-
-## Skill citations
-
-Specialist personas need at least one skill citation to earn their
-slot. Current cite map:
-
-| Persona | Cited by |
-|---|---|
-| `qa` | `judge-test-coverage` |
-| `critical-challenger` | `adversarial-review`, `requesting-code-review`, `receiving-code-review` |
-| `developer` · `senior-engineer` · `product-owner` · `ai-agent` | `refine-ticket`, `refine-prompt`, `estimate-ticket` |
-| `backend-architect` | `authz-review`, `api-design`, `blast-radius-analyzer` |
-| `eloquent-tamer` | `eloquent`, `database` |
-| `security-engineer` | `judge-security-auditor`, `threat-modeling`, `authz-review` |
-| `frontend-engineer` | `existing-ui-audit`, `fe-design` |
-| `brand-strategist` | `brand`, `brand-strategy` |
-| `design-director` | `brand-identity`, `logo-generation`, `brand-asset-generation` |
-
-Add a citation by appending `personas: [<id>]` to the skill's
-frontmatter — never overwrite an existing list, append.
-
-## Override pattern
-
-Consumers can override any package-shipped persona via the standard
-override mechanism:
-
-- **Frontmatter override** — change `tier`, `mode`, `description`
-  while keeping the package body. Frontmatter wins.
-- **Body override** — full replace. Drop a same-named file under
-  `agents/personas/<id>.md`; the package version is shadowed.
-
-See [`override-management`](../dist/agent-src/skills/override-management/SKILL.md)
-for the mechanics.
-
-## Anti-patterns
-
-- **Personas as agents.** Personas are lenses, not sub-agents. They do
-  not spawn processes or run tools independently.
-- **Personas as modes.** They do not change the host's contract or
-  refuse work. Use `/mode` for that.
-- **Specialist sprawl.** Cap is "≤ 4 specialists per plate" by the
-  council A-OQ2 verdict. New specialists need ≥ 1 skill citation
-  before merging.
-- **Core-tier mutation.** Core personas are versioned (`version` in
-  frontmatter); breaking changes need a new ID, not an in-place
-  rewrite.

package/docs/positioning-evidence.md

@@ -1,86 +0,0 @@
-# Positioning evidence & decision (B0)
-
-> Market-readiness roadmap B0. The evidenced differentiators the positioning
-> rests on, the H1 options that were weighed, and the decision. Every
-> differentiator below is **shipped and machine-checked**, not aspirational —
-> each names the artifact that backs it.
-
-## The problem
-
-External adoption is ≈0. The prior README H1 — *"Governed skills, rules & work
-journeys for AI coding agents"* — was abstract and interchangeable: no single
-uncopyable hook. This document fixes the one sentence that carries the
-differentiator.
-
-## Evidenced differentiators
-
-1. **Machine-checked honest marketing (the Claims-Ledger).** Every public claim
-   that carries a `<!-- claim:ID -->` marker must bind to a resolvable evidence
-   pointer in [`CLAIMS.md`](CLAIMS.md), or CI fails. Unbacked claims are logged
-   as visible debt rather than hidden. Evidence:
-   [`src/scripts/check_claims.ts`](../src/scripts/check_claims.ts),
-   [`CLAIMS.md`](CLAIMS.md).
-2. **A self-verifying proof page.** [`proof.md`](proof.md) is generated from the
-   ledger (claim → evidence table) plus the honest-null benchmark runs
-   (*including the nulls*) plus a "verify it yourself" command block a skeptic
-   runs on a fresh checkout. Drift-gated in CI. Evidence:
-   [`src/scripts/build_proof.ts`](../src/scripts/build_proof.ts),
-   [`proof.md`](proof.md).
-3. **Published honest-nulls.** Measured null results ship rather than hide (e.g.
-   a recursive-verification wrapper measured for null lift; an orchestration
-   auto-flip held at a documented honest-null). Evidence:
-   [`benchmark.md`](benchmark.md).
-4. **No-runtime, host-agnostic governance.** Rules compile into each tool's
-   native format at projection time; the same governance rides on 20 hosts with
-   no daemon. Surgical uninstall (JSON-pointer + SHA-256, never a neighbour
-   tool's keys). Evidence:
-   [`contracts/no-runtime-boundary.md`](contracts/no-runtime-boundary.md),
-   [`contracts/install-layout.md`](contracts/install-layout.md).
-5. **A 30-second wedge.** `production-validator` — a single self-contained Claude
-   Code subagent (one `curl` into `.claude/agents/`) that runs the last gate
-   before "done": no mock/stub on the shipped path, validated against real
-   systems. Evidence: [`wedge/production-validator/`](wedge/production-validator/).
-
-## Competitive frame
-
-The dominant competitor wins on reach behind a loud, **unbacked** headline
-performance number (present in several files, no reproducible methodology). The
-only defensible, uncopyable inverse is **reproducible honesty**: they cannot
-adopt a Claims-Ledger + proof page without exposing their own unbacked numbers.
-"Honesty" alone can read as merely defensive, so the wedge and the governed
-depth carry the offensive substance.
-
-## H1 options weighed
-
-- **Option 1 — verifiability as frame.** *"Agent Config — every claim
-  machine-checked, including 'zero runtime'."* Subline: 261 skills, 93 rules,
-  7 hosts; run the proof page yourself; no daemon, no lock-in, no unverifiable
-  promises.
-- **Option 2 — architecture first.** *"Governed AI agents with zero runtime —
-  and a proof page you verify in 30 seconds."*
-- **Option 3 — host-agnostic.** *"Write your agent governance once — run it in
-  7 hosts, with a proof page that can't lie."*
-
-## Decision
-
-**Adopted: Option 1** (verifiability as frame).
-
-Council (claude-sonnet-4-5 + gpt-4o, 2026-07-04) split only on headline vs.
-subline placement, and converged on the substance: the stateless / host-agnostic
-/ no-runtime architecture is the technical moat, and the Claims-Ledger + proof
-page is the maximally-uncopyable trust bootstrap. The decisive argument: in a
-low-trust market, "zero runtime" on its own is just another unverifiable
-promise — making **verifiability the frame** and the architectural claims *what
-you verify* is what makes "zero runtime" credible. The maintainer made the final
-call per the B0 "human picks" gate.
-
-**Biggest risk (tracked):** "machine-checked" can read as compliance-boring
-rather than a competitive weapon — mitigated by framing it offensively
-("built to be checked, in a market that runs on unbacked headlines"), not
-defensively.
-
-## Applied to
-
-- README H1 + hero line (this repo).
-- `distribution/launch-story-draft.md` headline placeholder (resolved).
-- `distribution/awesome-list-submission.md` (already Option-1-aligned).

package/docs/profiles.md

@@ -1,108 +0,0 @@
-# Six entry paths — by `profile.id`
-
-Each block below is the first-screen for one shipped profile. The
-`profile.id` written by `agent-config setup` 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
-[`src/agent-src/profiles/<id>.yml`](../src/agent-src/profiles/).
-
-The summary table at the top of [`README.md`](../README.md) is the
-one-page index; the prose below is the deep version.
-
-→ Each profile's **experience page** (packs · flows · what is *not* loaded ·
-examples) lives under [`docs/experiences/`](experiences/); the multi-command
-**work journeys** those profiles run are in [`docs/flows.md`](flows.md).
-
-**Switching experience.** `agent-config setup` writes `profile.id` on first run
-(it is the wizard's first question). To switch later, run
-`agent-config use --profile=<id>` (one of `developer` · `content_creator` ·
-`founder` · `agency` · `finance` · `ops`). In 6.0.0-A this records the choice
-only; pack-scoped surfacing (projection-time filtering,
-[`ADR-040`](decisions/ADR-040-execution-model-projection-time-filtering.md))
-activates in 6.0.0-B behind a staged, opt-in rollout.
-
-<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](../src/agent-src/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, render a cinematic AI video. `/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; `/video:from-script` and `/video:storyboard`
-drive the AI video pipeline (script → character-locked image →
-motion+audio prompt → provider render → stitched clip), with
-`character-consistency` locking identity tokens across scenes and
-`AIV_DRYRUN=true` as the cost-safety default.
-**Preset default: `balanced`.**
-[Profile YAML](../src/agent-src/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](../src/agent-src/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](../src/agent-src/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](../src/agent-src/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](../src/agent-src/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](../src/agent-src/user-types/galabau-field-crew.md),
-> [metalworking](../src/agent-src/user-types/metalworking-shop.md),
-> [truck driving](../src/agent-src/user-types/truck-driver.md) —
-> with a [scaffold](../src/agent-src/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)