README

Agent Config — every claim machine-checked, including "zero runtime daemon"

Try it in 30 seconds — drop one read-only subagent into any repo and watch it gate "done": @production-validator check this branch is actually done. No wizard, no lock-in, nothing else installed — the 30-second wedge ↓ is the whole first step. Start at the proof, not the catalog: event4u-app.github.io/agent-config/proof/.

Every public claim in this README is machine-checked — verify it yourself. In a market that runs on unbacked headline numbers, this one binds each claim to resolvable evidence or fails its own build.

Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump. Bring your own AI provider.

A deep library of skills, commands and governed rules — plus a capability router that loads the right skill on intent and multi-agent orchestration with consensus review. The whole layer is compiled into 20 host agents — of 23 detected, 3 being export-only (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini CLI, Codex, Continue, Zed, JetBrains, Aider and more) — with zero runtime daemon. Six role-shaped entry paths sit on top, so any host becomes a reliable team member — without locking you to a single model or vendor.

What's different

It is both deep and disciplined — and honest about what it deliberately is not:

• Depth that routes itself — a deep skill and command library, with a capability router that loads the right one on intent, not a 500-artefact context dump.
• Governance on every host — rules compiled into each tool's native format at projection time; deterministic runtime hooks added on hook-capable hosts. This config-space, host-agnostic governance is the moat (the governance advantage · enforcement by host).
• Surgical uninstall — removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries.
• Pack-scoped install — writes the active pack only, not a 500-artefact dump.

What it deliberately is not — the core is a governance layer with optional, individually opt-in embedded engines (code intelligence, gated reach, the setup GUI, the bench lab — ADR-124): no background daemon, no separate state database, no self-rewriting memory, no auto-build pipeline. Engines are never mandatory, never default-on without measured lift, and terminate with the command that invoked them. The host agent runs the loop; every learned change is human-reviewed; the same layer stays portable across tools. Capability without a process to babysit.

Where this comes from (honest provenance). The skills, rules and personas are distilled from real production work on TypeScript and PHP codebases. The governance mechanics are stack-agnostic, but the domain heuristics are richest where they were forged — treat coverage on other stacks as promising, not proven and tell us where it falls short.

See exactly what works on which host or jump to things you can do in a minute.

Pick your profile — six entry paths

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.

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: src/agent-src/profiles/ · schema: docs/contracts/profile-system.md. Beyond software: user-types/ (galabau · metalworking · truck — see Beyond software.

Per-profile experience pages (who it's for · first tasks · packs + flows · what is not loaded · examples): developer · content_creator · founder · agency · finance · ops.

Workflows, not raw commands

You don't memorize every command — you run a work journey. Four flows span the developer story end-to-end; each names the command you TYPE to start and the skills it composes:

Full detail — entry commands, canonical path, composed skills per flow: docs/flows.md. (agent-admin — memory / analytics / config — is platform operation, not a user-work flow.)

CHANGELOG · Upgrade to 6.0 · Breaking changes · Latest release · Discussions

_{Distribution: npm install @event4u/agent-config. Major bumps follow semver; each ships a ### Breaking entry — all majors indexed in BREAKING_CHANGES.md.}

Creative Pack — cinematic AI video. script → character-locked image → motion+audio prompt → provider render → stitched clip, with AIV_DRYRUN=true as the cost-safety default. A first-class capability inside the content / creator experience — no longer the package's headline. See /video:from-script.

Legal Pack — not legal advice. The EU/DE legal pack (contract/NDA/DPA review, triage) is a research-and-drafting aid only — it does not provide legal advice, does not replace a qualified lawyer and must not be relied on for any concrete matter. It produces general information and general templates, never individual-case examination. Read LEGAL_NOTICE.md before use.

Full catalog — every skill, rule, command, guideline: docs/catalog.md. The headline is the experience (profile + packs) and the depth behind it.

Use it in your project

Run from a consumer repo — bootstrap via npx, the agent picks up your stack and you ship work end-to-end. New install? Start with the Quickstart. Already installed? Supported tools shows the wired AIs; docs/featured-commands.md lists the end-to-end workflows (/implement-ticket, /work, /commit, /pr:create). Deeper tour: 2-minute demo.

Install scope. Pick one scope per machine — project-local (default, recommended for application repos) or user-global (recommended for tooling repos / dotfiles). The installer refuses a second, conflicting scope via the scope_guard pre-flight. Details: docs/contracts/install-scopes.md. Cleanup when needed: bash src/scripts/cleanup_other_scope.sh --confirm.

Prove it

Don't take the claims on trust — verify them. docs/proof.md is generated from source: a claim→evidence table (every public claim binds to a resolvable pointer or CI fails), honest-null benchmarks including the runs where the package changed nothing and a "verify it yourself" block you run on a fresh checkout. The proof page fails CI if it drifts from its sources — reproducibility is the proof. Browse it on the deployed docs site — the proof page is the primary entry: event4u-app.github.io/agent-config/proof/. The honest comparison frame lives at docs/us-vs-the-category.md.

Maintaining a skills catalog yourself? The anti-reskin gate that blocks find-replace re-skin PRs here runs on your catalog too — docs/anti-reskin-gate.md.

Audit-disciplined by construction — every memory consult, decision key and hook concern lands in agents/runtime/state/ so you can replay it. Core principles names the four invariants; What agent-config is — and what it isn't draws the scope boundary.

Contribute

Working on the package itself? Development covers the task ci pipeline, Requirements the toolchain, Maintainer telemetry the opt-in measurement loop. Source-of-truth tree is src/ (src/skills, src/rules, src/agent-src/); never hand-edit .augment/ or dist/agent-src/.

Security. Disclosure policy: SECURITY.md. Threat model: docs/threat-model.md.

Quickstart

Try one thing in 30 seconds — before the full suite, drop in a single self-contained subagent and see the discipline on your own repo:

mkdir -p .claude/agents
curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
  -o .claude/agents/production-validator.md
# then in Claude Code:  @production-validator check this branch is actually done

production-validator is read-only and installs nothing else — it gates "done" by hunting mocks/stubs on the shipped path and demanding real-system evidence (what it does). Like it? Install the full suite:

One command. Detection-driven — your installed AI tools are found and pre-selected. Nothing is written until you click Finish. No YAML by hand.

Those four are structural: they hold on every run, because they are properties of the code path rather than of your machine. How long it takes is not one of them — that is dominated by network and registry latency, which we do not control. The install → doctor wall-clock is measured by CI on every umbrella run and published with its conditions, as evidence; it is never a promised number.

# 1. Install — on a terminal with a display, the browser wizard launches
#    automatically; the same TypeScript installer runs the real install behind it.
npx -y @event4u/agent-config init

# 2. Pick your profile + tools in the wizard, click Finish.
#    (Writes ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …)

# 3. First real task — agent refines, plans, verifies.
/work "your first real task"

Headless / CI: init skips the GUI automatically on CI, on a non-TTY, on a headless host, and whenever any CLI-mode flag is present — it then runs the non-interactive installer directly. The full opt-out set is listed once, against the code, in gui-wizard § When the GUI is skipped. Pass flags (--profile=balanced --tools=claude-code,cursor); add --dry-run to preview writes. The GUI and the CLI share one installer (src/scripts/install.ts), so both produce identical results. Reference: docs/wizard.md.

Pick specific AIs: --tools=claude-code,cursor,augment,windsurf,cline,gemini-cli,copilot,roocode,aider,codex,claude-desktop,continue (any subset). Visual picker: add --gui (loopback-bound, CSRF-gated; contract gui-wizard). --gui is an opt-in that forces the wizard past the TTY and headless checks — it does not override CI, AGENT_CONFIG_NO_UI, or a CLI-mode flag; combining it with one of those exits non-zero rather than quietly running the CLI install. On a headless host add --allow-headless and connect a browser to the printed URL.

Verify hook coverage: npx @event4u/agent-config hooks:status prints the per-platform matrix (--strict for CI, --format json for tooling).

Scope (v2.5+): init writes global only — ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …. The project tree gets agents/overrides/ only (the bridge marker was retired — ADR-020 amendment 2026-07-13; the global root resolves from ~/.event4u/agent-config). --project is maintainer-only behind AGENT_CONFIG_DEV_MODE=1 (ADR-020, dev-mode).

Migrating from a v1.x install? npx @event4u/agent-config migrate — full notes in docs/migration/v1-to-v2.md.

What agent-config is — and what it isn't

A content layer — skills, rules, commands, guidelines, personas — distributed via npm and projected into every supported AI tool's native config format. It follows the Agent Skills open standard.

It is not an agent runtime. The agent loop, the LLM dispatcher and tool orchestration stay with the host tool (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI, Copilot). Think of it as a playbook and style guide for those tools — not a replacement.

What your agent is asked to do

2-minute demo — /implement-ticket

The flagship command. Drives a ticket end-to-end through a fixed linear flow — and blocks on ambiguity instead of guessing.

/implement-ticket PROJ-123

The agent runs this sequence:

refine → memory → analyze → plan → implement → test → verify → report

• Refines the ticket if acceptance criteria are vague.
• Queries memory for past decisions, invariants, incidents.
• Plans the change; you confirm before any file is touched.
• Implements under minimal-safe-diff + scope-control — no drive-by edits.
• Tests (targeted first, full suite on success).
• Reviews the diff through four judges (bugs, security, tests, code quality).
• Reports changes, verdicts, follow-ups — then stops. /commit and /pr:create are suggestions, never auto-run.

Any ambiguity halts the flow with numbered options — never a silent guess. Persona comes from .agent-settings.yml (roles.active_role): senior-engineer (default), qa or advisory (plan-only).

→ Command reference · Flow contract

Sibling — /work (free-form prompt)

Same engine, no ticket required:

/work add a CSV export endpoint to the audit-log controller

The first pass scores the prompt on five dimensions and routes on the band:

After the band gate, the flow is identical to /implement-ticket. Free-form goal → /work; ticket payload → /implement-ticket.

→ Command reference · refine-prompt skill

After the run: agent-config explain last reconstructs the trace (route · memory · council · halts · provider) — read-only, PII-scrubbed, offline. Docs

Product UI track

UI-shaped work routes to one of three directive sets — ui (full audit→design→apply→review→polish→report), ui-trivial (≤ 1 file, ≤ 5 lines: apply→test→report), mixed (backend + UI: contract→ui→stitch). Existing-UI audit is a hard gate (ui-audit-gate); polish has a 2-round ceiling with a11y precedence. Stack detection → blade-livewire-flux / react-shadcn / vue / plain.

→ Mental model (1 page) · Flow contract

Customize

Profiles — how much governance gets loaded

Safety floor (non-destructive defaults · ask-before-guessing · mirror-the-user's-language) ships in every profile. What changes is how much extra coaching gets pulled in.

Under the hood: kernel-only · kernel + tier-1 · kernel + tier-1 + tier-2. Details: rule-router · kernel-membership · Configure →.

Stability: STABILITY.md for the full matrix. Work Engine (/work + /implement-ticket): beta. Runtime Dispatcher: stable. Tool Adapters: experimental (full profile only).

.agent-user.md and Ghostwriter — voice primitives

Create the user file interactively: /agents user init (schema). Ghostwriter cluster: /ghostwriter:fetch <url-or-name> runs an attestation gate; private individuals rejected; paywalled / leaked / DM content banned at the schema level.

Self-hosted MCP on Cloudflare — zero local install

Skills, commands, rules and guidelines can be served as an MCP endpoint from your own Cloudflare Worker — any MCP client (Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents) talks to it over HTTP. Two auth modes: public (default, OSS read-only deploys) and bearer-auth (operator opt-in, MCP-Token Wrangler secret).

task mcp:cloud:login         # one-time, opens browser
task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private deploys)

→ Operator walkthrough: mcp-cloud-setup · Per-client config: mcp-client-config · Endpoints: mcp-cloud-endpoints.

Scope — Lite, not Full. The Worker serves read-only governance (skills · commands · rules · guidelines · contexts) as MCP prompts and resources, plus small read-only tools (memory_lookup, chat_history_read, list_*). It does not execute the ~112 Python scripts (linters, audits, task ci, work-engine hooks) — those require local install per Quickstart.

The built-in local stdio server is listed for discovery in the Glama MCP Registry (agent developers / contributors; requires a local checkout, not a turnkey install — see ADR-067).

Deployment posture

The Hard Floor on organization-mode features (SSO, central policy, OAuth connectors, team-context) is preserved by design — they stay cancelled until a real first customer + funded security audit lifts them. The small-team recipe is the supported path in the meantime.

The 9.3/10 feedback round (2026-05-25) re-asked for OAuth knowledge connectors, IAM / org governance and organization-shared memory. Each is a stable cancellation row in team-deployment-posture under the same three release gates — recruited team customer · funded audit · maintainer ADR.

Harness expectations

Three classes of install/runtime behaviour look like package bugs but are host-harness behaviour the package cannot control — sibling-plugin namespaces (codex:*, cc-gemini-plugin:*), deferred tools surfaced via ToolSearch and cross-scope skill drift (real bug, fixed in the distribution-channels track). Diagnostics + the package's response: docs/contracts/harness-expectations.md. First step when a skill appears twice: task probe:skills.

Supported tools

Project-installed (npx)

✅ native   ☑️ text reference (in AGENTS.md, not invokable as native slash-command)   📌 marker only   — not available

Team reproducibility: every tool you init is recorded in agents/installed-tools.lock (committed, machine-managed). New team members run npx @event4u/agent-config sync after cloning; CI gates drift with agent-config validate. Schema: installed-tools-manifest.

Plugin-installed (optional, global)

Claude Code: the marketplace plugin is deprecated (single-surface model). The npx/npm file projection now carries content and the deterministic hooks (registered in a managed ~/.claude/settings.json block by agent-config global / upgrade), so the plugin only duplicates skill/command listings while its git-SHA snapshot rots silently. Existing installs: claude plugin uninstall agent-config@event4u-agent-config — agent-config doctor flags the duplicate surface.

Keep the global install current with agent-config upgrade (latest) or agent-config refresh --global (same-version re-install); agent-config doctor flags a missing-from-PATH binary or broken hook wiring. See getting-started § Keeping current · Troubleshooting.

The command surface at a glance

Cloud / Hosted-agent surfaces

For platforms where the package's scripts cannot run, artefacts are built for paste-in or upload:

• Linear AI (Codegen, Charlie, …) — dist/linear/{workspace,team,personal}.md
• Claude.ai Web Skills — dist/cloud/<skill>.zip

→ Install →

Works with agent-switch

agent-switch is the companion CLI for running several agent accounts on one machine: it isolates each account in its own profile (CLAUDE_CONFIG_DIR per profile), so switching accounts never means logging out and back in. The two compose — agent-switch isolates the accounts, agent-config governs what the agents do inside them. When agent-config runs under an agent-switch profile it says so in the settings hub, warns before writes that would land in a shared (cross-profile) tree, and accepts a host-supplied config root so its own settings stay profile-scoped.

→ How the two compose →

Who this is for

Stack-agnostic governance core (orchestration · role modes · command clusters · quality gates · audit-discipline) plus parallel stack-specific skill sets:

Beyond software

The same orchestration core drives non-software trades via user-types/: galabau-field-crew · metalworking-shop · truck-driver. Contribute your own — 5-minute scaffold.

Data governance & domain safety

Three domain-safety rules (domain-safety-pii, domain-safety-disclaimer, domain-safety-retention) act as per-domain output floors across ~12 areas — PII redaction (support / finance / recruiting / marketing), advice disclaimers (legal / financial / medical / consulting), retention guidance (finance / support), ops floors (logging / export). Full surface → rule → floor matrix: docs/safety.md. Beta contracts: memory-visibility-v1 · decision-trace-v1.

Code provenance & license governance

Every diff is checked against a license policy derived from the target repo's own detected license (LICENSE/package.json/composer.json, precedence-ordered; sources disagree → escalate, never guess) and a strict linter over our own borrow ledger (provenance/borrows.jsonl → docs/THIRD-PARTY-NOTICES.md) that fails a deny-class license, an unknown license, a missing transformation note or a rename-only-phrased one — wired into ci/ci-strict from day one. A third piece, license-compliance-audit, runs an offline/online similarity scan on demand — a human invokes it deliberately, never a pipeline. This is provenance-governed, license-policy-enforced borrow discipline backed by an audited borrow trail — not a copy detector.

Scope & limits

• Unconscious training-data reproduction is not detectable at this layer. No tool here — or anywhere — can see what a model's training data contained; this system governs what gets consciously borrowed and recorded, never what a model silently recalls.
• Detection, where it exists, covers a knowledge base of known OSS only — a subset of all code that has ever existed, never a model's training corpus.
• No CI-facing detection gate exists. A deterministic scanner (jscpd offline + SCANOSS online) was built and measured against a frozen synthetic corpus, but missed its own pre-registered thresholds (measured: recall 12/16, false positives 2/12, SCANOSS rename-only recall 0/8) — see docs/CLAIMS.md. It ships in no form in CI, not even advisory — only as the on-demand skill above.
• Rename-only laundering is not detected by anything we ship or evaluated. The ledger's transformation-note check rejects a rename-only-phrased note, but it cannot catch an undisclosed rename-only copy that was never logged.

Reduces and documents risk — never eliminates it.

Maintainer telemetry (opt-in, default-off)

Local-only artefact-engagement log. Set telemetry.artifact_engagement.enabled: true in .agent-settings.yml. Records which skills / rules / commands / guidelines the agent consults during /implement-ticket / /work. JSONL under the project root, nothing uploaded. Reports: npx @event4u/agent-config telemetry:report.

Context-aware command suggestion

When a prompt matches a command's purpose ("setze ticket ABC-123 um" → /implement-ticket), the agent surfaces matches as numbered options — nothing auto-executes. Per-conversation off: /command-suggestion-off. Settings: commands.suggestion.{enabled,blocklist,confidence_floor} in .agent-settings.yml.

Core principles

• Analyze before implementing — no guessing, no blind edits
• Verify with real execution — no "should work"
• Challenge to improve — agents are thought partners, not yes-machines
• Strict by design — quality over flexibility
• Zero overhead by default — nothing runs until you ask for it

Documentation

Browse content: all commands · skills catalog · full catalog · llms.txt.

Troubleshooting

First stop for any install problem: agent-config doctor — it flags a missing-from-PATH binary, binary↔plugin version drift, stale orphans and manifest issues, each with a one-line fix hint.

For "why didn't rule/hook X fire?" questions: agent-config routing:doctor — a read-only, live diagnosis that reports every session-start gate as ACTIVE/INACTIVE with the concern's own reason (e.g. session-canary: ACTIVE for "Alex" vs INACTIVE — no name on any settings layer), the platform's concern chain, host hook registration, and router + projection freshness. Deeper hook internals (fail-open/closed posture, last dispatcher feedback per concern): agent-config hooks:doctor.

A new command / skill is missing in Claude Code after an upgrade

Under the single-surface model, agent-config upgrade refreshes the ~/.claude/ file projection — that IS the content surface, so a fresh session picks the new commands up directly. If commands are still missing, the usual cause is a leftover marketplace plugin: it is a git-SHA snapshot that never moves with the npm upgrade and it shadows nothing — it just lists everything twice while lagging behind. Remove it:

claude plugin uninstall agent-config@event4u-agent-config

Then start a new Claude Code session. agent-config doctor reports a leftover plugin as claude-plugin: duplicate surface; hooks are unaffected (they live in a managed ~/.claude/settings.json block — verify with the hook-wiring check).

Skills / commands appear twice in Claude Code

Same cause as above: the deprecated marketplace plugin is installed next to the ~/.claude/ file projection, so every skill lists plain and agent-config:-prefixed. Uninstall the plugin (command above) and start a new session.

agent-config upgrade fails with Unknown argument: --no-ui

Known bug in 8.2.0: upgrade passed a --no-ui flag that the install orchestrator did not accept yet, so the run aborted early. Fixed on main; until the next release, work around it with:

AGENT_CONFIG_NO_UI=1 agent-config global   # refresh the global install, no wizard

Upgrade was interrupted (Ctrl-C, wizard closed, step failed)

Only the initial npm install -g hard-aborts an upgrade. Every later step (global re-deploy with hook registration, settings sync, wrapper + git-hook refresh) runs independently — a single failed step is reported in the end-of-run summary instead of silently skipping the rest. Re-run agent-config upgrade to converge and use agent-config doctor to name anything left in a mixed state.

agent-config: command not found / hooks stopped firing

Runtime hooks resolve the global binary on PATH — a project-local install alone is not enough for them. Reinstall the binary:

npm install -g @event4u/agent-config
agent-config doctor   # verifies PATH + plugin wiring

Project files look stale after a package update

Project-local projections are only rewritten on an explicit refresh:

agent-config refresh             # re-apply the installed version to this project
agent-config refresh --global    # same-version re-install of the global root

More per-version steps: Migration · getting-started § Keeping current.

Development

Working on the package itself? Edit src/ (the source of truth — src/skills, src/rules, src/agent-src/), regenerate trees:

task sync             # regenerate dist/agent-src/ and .augment/
task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
task ci               # full pipeline — green before PR
task test             # unit + integration tests
task dev:setup        # boot the onboarding wizard against the working tree

Invoking the CLI from a source checkout: ./agent-config <command> (the maintainer shim at the repo root → scripts/agent-config → dist/cli/agent-config.js). npx @event4u/agent-config doesn't resolve in the source repo without a prior npm link, since there's no node_modules/.bin/agent-config symlink — use ./agent-config instead. Build the TS binary with npm run build:cli if dist/cli/agent-config.js is missing.

→ Full project structure and commands: docs/development.md · CONTRIBUTING.md. Stack: TypeScript CLI/UI + Python 3.10+ build/lint scripts. MCP registry payloads render under dist/mcp/ (submission checklist).

Requirements

• Node ≥ 20.11 — npx @event4u/agent-config init is the canonical install path. No Python anywhere on the install path (the Python installer retired with the TypeScript migration).
• Platform: macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks. Contributors rebuilding .augment/ also need Task.

Windows

Native PowerShell / cmd is not supported for the file install — use WSL2 for the full installed tree. The supported native-Windows surface is the MCP stdio server: point any MCP client at

npx -y @event4u/agent-config mcp-server

and the governance content (prompts, resources, tools) is available without the file install. Porting the bash dispatcher to native Windows is demand-gated: a named Windows adopter who cannot use WSL2 or the MCP path reopens it (see agents/roadmaps/ — road-to-credible-install Phase 3).

Funding

The package is free, MIT, and stays that way — no paid tier, no dual licensing. If it saves you time and you want to chip in, the GitHub Sponsor button at the top of the repo is the whole mechanism. If you would rather not, use it anyway; nothing here is gated on it.

License

MIT.

mcp-name: io.github.event4u-app/agent-config