@event4u/agent-config 2.25.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 # Agent Config — Universal AI Agent OS
 
-[![Skills](https://img.shields.io/badge/Skills-216-1f6feb?style=flat-square)](.augment/skills/) [![Rules](https://img.shields.io/badge/Rules-84-d73a49?style=flat-square)](.augment/rules/) [![Commands](https://img.shields.io/badge/Commands-129-2da44e?style=flat-square)](.augment/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-73-8957e5?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-bf8700?style=flat-square)](docs/personas.md) [![Advisors](https://img.shields.io/badge/Advisors-5-fb8500?style=flat-square)](docs/profiles.md) [![AI Tools](https://img.shields.io/badge/AI%20Tools-8-1abc9c?style=flat-square)](docs/architecture.md) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Skills](https://img.shields.io/badge/Skills-218-1f6feb?style=flat-square)](.augment/skills/) [![Rules](https://img.shields.io/badge/Rules-72-d73a49?style=flat-square)](.augment/rules/) [![Commands](https://img.shields.io/badge/Commands-128-2da44e?style=flat-square)](.augment/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-73-8957e5?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-bf8700?style=flat-square)](docs/personas.md) [![Advisors](https://img.shields.io/badge/Advisors-5-fb8500?style=flat-square)](docs/profiles.md) [![AI Tools](https://img.shields.io/badge/AI%20Tools-8-1abc9c?style=flat-square)](docs/architecture.md) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 
 > **A deterministic orchestration contract for AI agents — audited skills, governance rules, replayable state — usable by developers, founders, and creators alike.**
 
@@ -12,9 +12,9 @@ Give your AI agents an audit-disciplined execution layer: multiple **skills**, *
 
 ### Pick your profile — six entry paths
 
-`/onboard` writes `profile.id` to `.agent-settings.yml`; each anchor
-below is the first-screen the wizard sends you to. One README, six
-entries, no role-detection guesswork.
+`agent-config setup` writes `profile.id` to `.agent-settings.yml`; each
+anchor below is the first-screen the wizard sends you to. One README,
+six entries, no role-detection guesswork.
 
 | Profile (`profile.id`) | Audience | First commands | First skills |
 |---|---|---|---|
@@ -25,9 +25,9 @@ entries, no role-detection guesswork.
 | 💼 [`finance`](docs/profiles.md#profile-finance) | CFO / fractional finance / FP&A | `/work` · `/council` · `/challenge-me` | `dcf-modeling` · `forecasting` · `scenario-modeling` · `unit-economics-modeling` · `runway-cognition` |
 | 🛡 [`ops`](docs/profiles.md#profile-ops) | RevOps, support, SRE-adjacent | `/work` · `/threat-model` · `/review-changes` · `/fix` | `incident-commander` · `dashboard-design` · `logging-monitoring` · `threat-modeling` · `launch-readiness` |
 
-**Not sure which one?** Run `npx @event4u/agent-config init` and open
-your AI agent — `/onboard` asks a single 8-option role question and
-maps to the closest profile. Source-of-truth:
+**Not sure which one?** Run `npx @event4u/agent-config init` then
+`agent-config setup` — the browser wizard asks a single 8-option role
+question and maps to the closest profile. Source-of-truth:
 [`.agent-src.uncompressed/profiles/`](.agent-src.uncompressed/profiles/) ·
 schema: [`docs/contracts/profile-system.md`](docs/contracts/profile-system.md).
 Beyond software: [`user-types/`](.agent-src.uncompressed/user-types/)
@@ -53,7 +53,7 @@ lists the end-to-end workflows (`/implement-ticket`, `/work`,
 ## Prove it
 
 Audit-disciplined by construction — every memory consult, decision
-key, and hook concern lands in `agents/state/` so you can replay it.
+key, and hook concern lands in `agents/runtime/state/` so you can replay it.
 [Core Principles](#core-principles) names the four invariants;
 [What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
 draws the scope boundary. Beta contracts:
@@ -76,16 +76,17 @@ opt-in measurement loop. Source-of-truth tree is
 # 1. Install (writes .agent-settings.yml, .augment/, .claude/, …)
 npx @event4u/agent-config init
 
-# 2. First-run setup (sets your name, IDE, cost profile)
-#    Open your AI agent (Claude Code, Cursor, …) and type:
-/onboard
+# 2. First-run setup — browser wizard (writes .agent-settings.yml)
+agent-config setup                # browser, lands on #/wizard
 
 # 3. First real task — agent refines, plans, logs a decision_result
 /work "your first real task"
 ```
 
-A `decision_result` entry lands in `agents/state/` confirming the
-work-engine phases ran end-to-end. Stack-aware skills auto-load.
+The wizard uses the `commitMulti` 2PC substrate to write
+`.agent-settings.yml` (and optional `.agent-user.md`) atomically — see
+[`docs/wizard.md`](docs/wizard.md). A `decision_result` lands in
+`agents/runtime/state/`. Stack-aware skills auto-load.
 
 > Pick specific AIs, switch to global scope, deploy MCP on Cloudflare,
 > or wire optional memory — see [**Detailed installation**](#detailed-installation)
@@ -400,6 +401,8 @@ to `/implement-ticket`. UI-shaped prompts are routed through the
 Free-form goal, no ticket → `/work`. The two share `.work-state.json`
 and refuse to switch envelopes mid-flight.
 
+**After the run:** `agent-config explain last` reconstructs the trace (route · memory · council · halts · provider) — read-only, PII-scrubbed, offline. [Docs](docs/customization.md#explainability--explain-last)
+
 ### Product UI track
 
 UI-shaped work (build a screen, improve a component, fix microcopy)
@@ -478,7 +481,7 @@ how to behave, not how to execute.
 
 Example of what *is* in scope: every artefact's frontmatter validates
 against a JSON-Schema under [`scripts/schemas/`](scripts/schemas/)
-([contract](agents/docs/frontmatter-contract.md)), enforced by
+([contract](agents/reference/docs/frontmatter-contract.md)), enforced by
 `task validate-schema` in CI. Runtime validation inside a live agent
 session is explicitly not.
 
@@ -545,7 +548,7 @@ Deep version of the profile table above (audience · first commands ·
 first skills · preset default per profile):
 [`docs/profiles.md`](docs/profiles.md). Curated featured-commands
 subset: [`docs/featured-commands.md`](docs/featured-commands.md).
-[Browse all 129 active commands](.agent-src/commands/) · full catalog:
+[Browse all 128 active commands](.agent-src/commands/) · full catalog:
 [`docs/catalog.md`](docs/catalog.md) ·
 [skills only](docs/skills-catalog.md) · [`llms.txt`](llms.txt).
 
@@ -579,7 +582,7 @@ slash-commands)   📌 = informational marker only (no auto-discovery
 or manual wiring required)
 
 > **What this means in practice:** Claude Code gets the full project-scoped
-> package (rules + 216 skills + 129 native commands); Augment Code gets the
+> package (rules + 218 skills + 128 native commands); Augment Code gets the
 > same content but only from a single global install at `~/.augment/`.
 > Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
 > and Continue.dev only get the **rules** natively; skills and commands are
@@ -643,14 +646,14 @@ Create it interactively with `/agents user init`. Inspect with
 legacy `personal.user_name` key in `.agent-settings.yml` stays as a
 fallback when `.agent-user.md` is absent.
 
-## Ghostwriter (`agents/ghostwriter/<slug>.md`)
+## Ghostwriter (`agents/reference/ghostwriter/<slug>.md`)
 
 Third voice primitive — captures **public-facing writing voice of
 documented public figures** (authors, executives, academics,
 journalists, public speakers, deceased historical figures).
 `/ghostwriter:fetch <url-or-name>` runs an attestation gate, delegates
 to the host agent's `web-fetch` / `web-search` (zero network code in
-the package), and writes `agents/ghostwriter/<slug>.md` — **gitignored
+the package), and writes `agents/reference/ghostwriter/<slug>.md` — **gitignored
 by default**, never shipped in the OSS package. `/ghostwriter:write
 --as=<slug>` drafts in that voice and appends the **mandatory
 non-removable disclosure footer** (`*Written in the style of <name>,
@@ -663,7 +666,7 @@ Schema: [`docs/contracts/ghostwriter-schema.md`](docs/contracts/ghostwriter-sche
 |---|---|---|
 | `personas/*.md` | review-lens (internal critique) | n/a |
 | `.agent-user.md` | maintainer's own voice (`/post-as:me`) | none — you are the author |
-| `agents/ghostwriter/<slug>.md` | external public-figure (`/post-as:ghostwriter`) | mandatory, non-removable |
+| `agents/reference/ghostwriter/<slug>.md` | external public-figure (`/post-as:ghostwriter`) | mandatory, non-removable |
 
 ## Core Principles
 
@@ -733,7 +736,7 @@ task ci               # full pipeline — green before PR
 task test             # unit + integration tests
 ```
 
-→ Full commands and project structure: [**docs/development.md**](docs/development.md)
+→ Full commands and project structure: [**docs/development.md**](docs/development.md). Stack: **TypeScript** CLI/UI (`dist/cli/`, `dist/ui/`) + **Python 3.10+** build/lint scripts. Prompt-engineering primitives — `/optimize-prompt`, `/refine-prompt`, the `prompt-engineering-patterns` skill — ship for every host agent. MCP registry payloads render under `dist/mcp/` (submissions tracked in [`docs/distribution/mcp-submission-checklist.md`](docs/distribution/mcp-submission-checklist.md)).
 
 ## Requirements
 

package/config/agent-settings.template.yml

@@ -147,7 +147,7 @@ eloquent:
 
 # --- Chat history (crash recovery) ---
 #
-# Persistent JSONL log at agents/.agent-chat-history (git-ignored).
+# Persistent JSONL log at agents/runtime/.agent-chat-history (git-ignored).
 # Keeps a durable record of the conversation so a crashed or switched
 # agent session can be resumed. See scripts/chat_history.py for the API.
 chat_history:
@@ -496,3 +496,13 @@ decision_engine:
 # matrix and the road-to-portable-runtime-and-update-check roadmap (P2).
 update_check:
   enabled: true
+
+# ─── explain ──────────────────────────────────────────────────────────────
+# `agent-config explain last` renders the read-only execution trace for the
+# most recent /work run (state file `.work-state.json`). Trace output is
+# PII-scrubbed before emission; the command never makes network calls and
+# never writes to state. Set `enable_last: false` to suppress the subcommand
+# (the call still exits 0 with a one-line notice — used by air-gapped
+# tenants that disable diagnostics surface-wide).
+explain:
+  enable_last: true

package/config/discovery/packs.yml

@@ -0,0 +1,142 @@
+# Discovery packs — closed vocabulary
+#
+# Source of truth: docs/decisions/ADR-013-discovery-frontmatter-contract.md §packs
+# Amendments require an ADR-013 amendment in the same PR.
+# `requires_hint` is advisory metadata only; runtime does NOT act on it.
+# Lint: scripts/lint_discovery_vocabulary.py
+
+- id: engineering-base
+  label: Engineering Base
+  description: Framework-neutral engineering hygiene — git, tests, reviews.
+  workspaces: [engineering]
+  trust_level_default: core
+
+- id: php
+  label: PHP
+  description: PHP-language patterns (framework-free).
+  workspaces: [engineering]
+  requires_hint: [engineering-base]
+  trust_level_default: professional
+
+- id: laravel
+  label: Laravel
+  description: Laravel framework patterns; depends on PHP at the artefact level.
+  workspaces: [engineering]
+  requires_hint: [php, engineering-base]
+  trust_level_default: professional
+
+- id: symfony
+  label: Symfony
+  description: Symfony framework patterns; depends on PHP at the artefact level.
+  workspaces: [engineering]
+  requires_hint: [php, engineering-base]
+  trust_level_default: professional
+
+- id: javascript
+  label: JavaScript
+  description: JavaScript-language patterns.
+  workspaces: [engineering]
+  requires_hint: [engineering-base]
+  trust_level_default: professional
+
+- id: typescript
+  label: TypeScript
+  description: TypeScript-language patterns.
+  workspaces: [engineering]
+  requires_hint: [javascript, engineering-base]
+  trust_level_default: professional
+
+- id: react
+  label: React
+  description: React framework patterns.
+  workspaces: [engineering]
+  requires_hint: [javascript, engineering-base]
+  trust_level_default: professional
+
+- id: nextjs
+  label: Next.js
+  description: Next.js framework patterns.
+  workspaces: [engineering]
+  requires_hint: [react, typescript, engineering-base]
+  trust_level_default: professional
+
+- id: python
+  label: Python
+  description: Python-language patterns.
+  workspaces: [engineering]
+  requires_hint: [engineering-base]
+  trust_level_default: professional
+
+- id: product-basic
+  label: Product Basic
+  description: Core PO/PM artefacts (ticket refinement, AC, estimation).
+  workspaces: [product]
+  trust_level_default: professional
+
+- id: product-discovery
+  label: Product Discovery
+  description: JTBD, interviews, VoC, hypothesis testing.
+  workspaces: [product]
+  requires_hint: [product-basic]
+  trust_level_default: professional
+
+- id: finance-basic
+  label: Finance Basic
+  description: Cashflow, runway, basic forecasting.
+  workspaces: [finance, founder]
+  trust_level_default: professional
+
+- id: finance-advanced
+  label: Finance Advanced
+  description: DCF, scenario modelling, comp banding.
+  workspaces: [finance]
+  requires_hint: [finance-basic]
+  trust_level_default: core
+
+- id: gtm-sales
+  label: GTM — Sales
+  description: Pipeline, MEDDIC, forecast accuracy.
+  workspaces: [gtm]
+  trust_level_default: professional
+
+- id: gtm-marketing
+  label: GTM — Marketing
+  description: Positioning, messaging, editorial, content funnel.
+  workspaces: [gtm, founder]
+  trust_level_default: professional
+
+- id: ops-people
+  label: Operations — People
+  description: Hiring loops, onboarding programs, comp banding.
+  workspaces: [ops]
+  trust_level_default: professional
+
+- id: founder-strategy
+  label: Founder — Strategy
+  description: Vision, fundraising narrative, competitive moat.
+  workspaces: [founder]
+  trust_level_default: core
+
+- id: small-business
+  label: Small Business
+  description: SMB-shaped owner workflows.
+  workspaces: [small-business]
+  trust_level_default: professional
+
+- id: construction
+  label: Construction
+  description: Trade-business workflows.
+  workspaces: [construction]
+  trust_level_default: professional
+
+- id: ai-video
+  label: AI Video
+  description: AI video pipeline (per ADR-011, the only heavyweight domain).
+  workspaces: [small-business]
+  trust_level_default: experimental
+
+- id: meta
+  label: Meta
+  description: Artefacts that maintain this package (agent-config itself).
+  workspaces: [agent-config-maintainer]
+  trust_level_default: core

package/config/discovery/unassigned-artefacts.yml

@@ -0,0 +1,66 @@
+# Discovery — unassigned-artefact quarantine
+#
+# Catch-all for artefacts that legitimately resist workspace/pack
+# assignment. Each entry MUST carry a `reason:` field.
+#
+# Stays empty through Phases 1–3 of
+# `agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md`
+# (archived, status: completed). Phase 4 populated it with the
+# genuinely cross-cutting cases listed below.
+#
+# Lint: scripts/lint_artefact_frontmatter.py (added in Phase 6)
+# Schema entry shape:
+#
+#   - path: <repo-relative-path-to-artefact>
+#     reason: <one-line explanation>
+
+# Scaffold templates — markdown skeletons consumed by `/agents init`,
+# /skill-management, /override:create, etc. They carry no runtime
+# frontmatter on purpose: the consuming command fills it in. Quarantined
+# from the discovery manifest so strict mode stays clean.
+- path: .agent-src.uncompressed/templates/AGENTS.md
+  reason: scaffold template for new project AGENTS.md; placeholders filled by /agents init
+- path: .agent-src.uncompressed/templates/agent-settings.md
+  reason: scaffold for project .agent-settings.yml
+- path: .agent-src.uncompressed/templates/command.md
+  reason: scaffold for new slash-command authoring
+- path: .agent-src.uncompressed/templates/contexts.md
+  reason: scaffold index for project contexts/
+- path: .agent-src.uncompressed/templates/contexts/auth-model.md
+  reason: scaffold for project auth-model context
+- path: .agent-src.uncompressed/templates/contexts/data-sensitivity.md
+  reason: scaffold for project data-sensitivity context
+- path: .agent-src.uncompressed/templates/contexts/deployment-order.md
+  reason: scaffold for project deployment-order context
+- path: .agent-src.uncompressed/templates/contexts/observability.md
+  reason: scaffold for project observability context
+- path: .agent-src.uncompressed/templates/contexts/tenant-boundaries.md
+  reason: scaffold for project tenant-boundaries context
+- path: .agent-src.uncompressed/templates/copilot-instructions.md
+  reason: scaffold for project copilot-instructions.md
+- path: .agent-src.uncompressed/templates/features.md
+  reason: scaffold for project features.md catalogue
+- path: .agent-src.uncompressed/templates/overrides/command.md
+  reason: scaffold for project override of a shared command
+- path: .agent-src.uncompressed/templates/overrides/guideline.md
+  reason: scaffold for project override of a shared guideline
+- path: .agent-src.uncompressed/templates/overrides/rule.md
+  reason: scaffold for project override of a shared rule
+- path: .agent-src.uncompressed/templates/overrides/skill.md
+  reason: scaffold for project override of a shared skill
+- path: .agent-src.uncompressed/templates/overrides/template.md
+  reason: scaffold-of-scaffold for new override types
+- path: .agent-src.uncompressed/templates/persona.md
+  reason: scaffold for new persona authoring
+- path: .agent-src.uncompressed/templates/roadmaps.md
+  reason: scaffold for new roadmap authoring
+- path: .agent-src.uncompressed/templates/rule.md
+  reason: scaffold for new rule authoring
+- path: .agent-src.uncompressed/templates/scripts/.pytest_cache/README.md
+  reason: pytest cache artefact, not an agent-config artefact
+- path: .agent-src.uncompressed/templates/scripts/README.md
+  reason: scaffold README for project scripts/
+- path: .agent-src.uncompressed/templates/skill-archive-note.md
+  reason: scaffold for archive-note generation
+- path: .agent-src.uncompressed/templates/skill.md
+  reason: scaffold for new SKILL.md authoring

package/config/discovery/workspaces.yml

@@ -0,0 +1,59 @@
+# Discovery workspaces — closed vocabulary
+#
+# Source of truth: docs/decisions/ADR-013-discovery-frontmatter-contract.md §workspaces
+# Amendments require an ADR-013 amendment in the same PR.
+# Lint: scripts/lint_discovery_vocabulary.py
+
+- id: engineering
+  label: Engineering
+  description: Code, tests, CI, reviews, architecture.
+  default_packs: [engineering-base]
+  optional_packs: [php, laravel, symfony, javascript, typescript, react, nextjs, python]
+
+- id: product
+  label: Product
+  description: Discovery, roadmaps, prioritisation, AC tightening.
+  default_packs: [product-basic]
+  optional_packs: [product-discovery]
+
+- id: finance
+  label: Finance / CFO
+  description: Cashflow, forecasting, DCF, board reporting.
+  default_packs: [finance-basic]
+  optional_packs: [finance-advanced]
+
+- id: founder
+  label: Founder
+  description: Strategy, fundraising, vision, board narrative.
+  default_packs: [founder-strategy]
+  optional_packs: [finance-basic, gtm-marketing]
+
+- id: gtm
+  label: Go-to-Market
+  description: Sales pipeline, marketing, positioning, launch.
+  default_packs: [gtm-sales, gtm-marketing]
+  optional_packs: []
+
+- id: ops
+  label: Operations
+  description: Hiring, comp, perf, org design, runbooks.
+  default_packs: [ops-people]
+  optional_packs: []
+
+- id: small-business
+  label: Small Business
+  description: Self-employed / SMB-shaped owner workflows.
+  default_packs: [small-business]
+  optional_packs: [ai-video]
+
+- id: construction
+  label: Construction
+  description: Trade-business workflows (planning, quotes).
+  default_packs: [construction]
+  optional_packs: []
+
+- id: agent-config-maintainer
+  label: Maintainer
+  description: Skills/rules/commands that maintain this package.
+  default_packs: [meta]
+  optional_packs: []

package/config/gitignore-block.txt

@@ -37,7 +37,10 @@
 !/agents/ghostwriter/README.md
 /agents/ghostwriter/*.md.bak
 
-# Agent config — persistent chat history (crash recovery, never commit)
+# Agent config — legacy chat-history flat path. Current installs put
+# the file at agents/runtime/.agent-chat-history (covered by the
+# /agents/runtime/ catch-all below). Kept for back-compat with older
+# installs that have not migrated yet.
 /agents/.agent-chat-history
 /agents/.agent-chat-history.bak
 /agents/.agent-chat-history.*.bak
@@ -46,23 +49,17 @@
 .agent-engagement.jsonl
 .agent-engagement.jsonl.bak
 
-# Agent config — AI Council price table (refreshed weekly, never commit)
-/agents/.agent-prices.md
+# Agent config — volatile runtime artefacts (machine-generated,
+# regenerated on demand, never committed). Single catch-all per the
+# Volatile Runtime policy: everything under agents/runtime/ is
+# local-only — price cache, council questions/responses/sessions,
+# council events log, Tier 1 hook runtime state, chat-history, budget
+# history, density / frugality / logs / mcp-telemetry / tmp scratch.
+# Durable evidence cited from docs / ADRs lives in agents/evidence/;
+# decision records in agents/decisions/.
+/agents/runtime/
 
-# Agent config — AI Council artefacts (questions, responses, sessions).
-# Dev-time scratch — informs decisions, never the durable contract.
-# See ai-council § Output path convention.
-/agents/council-questions/
-/agents/council-responses/
-/agents/council-sessions/
-
-# Agent config — AI Council persistent events log (step-8 D3).
-# Local JSONL audit trail for necessity / quota decisions. Hashes
-# original_ask before write but is still considered private. Set
-# AGENT_CONFIG_NO_EVENTS_LOG=1 to disable writes entirely.
-/agents/council-events.log
-
-# Agent config — Tier 1 hook runtime state (context-hygiene.json,
-# onboarding-gate.json). Written by SessionStart / PostToolUse hooks
-# on Augment + Claude Code; regenerated on demand, never commit.
-/agents/state/
+# Agent config — unified-setup wizard partial state (Roadmap R2 Phase 1).
+# Written by POST /api/v1/wizard/state between step transitions, deleted
+# on POST /api/v1/wizard/finish. Local-only crash-recovery aid.
+/.agent-config/wizard-state.json