Download the PHP package event4u/agent-config without Composer

Agent Config — every claim machine-checked, including the artifact counts in these badges

_{How these are counted — one canonical counter, agent-config → update_counts --check, re-derives all six from the tree and fails CI when one is off by one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: Commands 212 counts every command file recursively (the linked directory holds 63 at its top level) and Rules 122 counts the source rules while the linked projection holds 121 — one rule is dormant and is not projected. Personas 29 excludes the directory README. Counts are of files and directories: none of them measures quality, activation or adoption.}

Try it in 30 seconds — one read-only subagent checks "done" in any repo, nothing else installed: 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.

See what a change touches

agent-config code-graph map draws an offline map into agents/map/: code, data, systems, interfaces, runtime, delivery, history, domains. Facts keep file:line, re-read before acting. Pick a file: every reached area lights up.

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). Resident processes are permitted only under the supervision policy this repository adopted on 2026-08-27 — a rule, not a description of anything running today. 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.

Try it in 30 seconds

Or try one subagent first, on your own repo:

production-validator is read-only: it hunts mocks and stubs on the shipped path and demands real-system evidence (what it does). The full suite is one command — Quickstart ↓.

What's different

Deep and disciplined and honest about what it deliberately is not:

• Depth that routes itself — a capability router loads the right skill on intent, not a 500-artefact context dump.
• Governance on every host — rules compiled into each tool's native format; deterministic runtime hooks added on hook-capable hosts. This config-space, host-agnostic governance is the moat (enforcement by host).
• Surgical uninstall — its own keys in a shared config, never a neighbour's; under --purge, only files it recorded, never the anchor.
• Pack-scoped install — writes active pack plus dependencies; others are owed reach.

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 — the embedded-engine doctrine): no mandatory or always-on 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 things you can do in a minute.

Pick your profile — six entry paths

agent-config setup writes profile.id to .agent-settings.yml and sends you to that profile's first screen. Each experience page carries the full detail — who it's for, first commands and skills, packs and flows — and what is deliberately not loaded.

Not sure which one? The 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).

Workflows, not raw commands

You don't memorize commands — you run a work journey. Four flows span the developer story end-to-end:

Composed skills and the canonical path per flow: docs/flows.md.

CHANGELOG · Upgrade to 14.x · Breaking changes · Latest release · Discussions

_{Distribution: npm install @event4u/agent-config. Major bumps follow 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 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. Installer default: user-global (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. It fails CI if it drifts from its sources — reproducibility is the proof. Read it at event4u-app.github.io/agent-config/proof/, with the comparison frame at docs/us-vs-the-category.md. Freshest measured row: in one post-fix session, advisory context injection cut language-mirror violations 555 → 19 while the two blocking guards went 8 → 0 and 1 → 0 — advisory reduced massively, only blocking eliminated. One session and a post-hoc reading, so a recorded prior rather than a law.

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

Audit-disciplined — decision keys land in agents/runtime/state/; the replay journal is opt-in (hooks.runtime_journal.enabled). Core principles names the four invariants.

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: docs/threat-model.md.

Quickstart

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 — properties of the code path, not of your machine. How long it takes is not: that is dominated by network and registry latency. CI measures the install → doctor wall-clock on every umbrella run and publishes it with its conditions, as evidence rather than as a promise.

The one command is above ↑.

Headless / CI: init skips the GUI on CI, a non-TTY, a headless host or any CLI-mode flag; it runs the non-interactive installer instead. The GUI and the CLI share one installer (src/scripts/install.ts), so both produce identical results. Flags, the full opt-out set and --dry-run: gui-wizard § When the GUI is skipped.

Pick specific AIs: --tools=claude-code,cursor,augment,… (any subset). --gui forces the loopback-bound, CSRF-gated picker 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.

Verify hook coverage: npx @event4u/agent-config hooks:status (--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. --project is maintainer-only behind AGENT_CONFIG_DEV_MODE=1 (dev-mode).

Migrating from v1.x? npx @event4u/agent-config migrate — 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. Skills use SKILL.md with package-specific frontmatter keys.

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.

The agent runs this sequence:

• 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 seven judges (bugs, security, tests, quality, architecture, spec, overbuild).
• 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).

→ Flow contract

Sibling — /work (free-form prompt)

Same engine, no ticket required:

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.

→ 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.

→ 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, as a guardrail, not a security boundary. Profiles add coaching.

Under the hood: kernel-only · kernel + tier-1 · kernel + tier-1 + tier-2. Details: 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, reachable over HTTP by any MCP client. Two auth modes: public (default) and bearer-auth (operator opt-in, MCP-Token Wrangler secret).

→ Operator walkthrough: 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 repository's local scripts (linters, audits, task ci, work-engine hooks) — those require local install per Quickstart.

The built-in local stdio server is listed in the Glama MCP Registry — it requires a local checkout, not a turnkey install (ADR-067).

Deployment posture

Organization-mode features (SSO, central policy, OAuth connectors, team-context) stay cancelled by design until a recruited customer and a funded security audit lift them; the small-team recipe is the supported path meanwhile. Each is a stable cancellation row in team-deployment-posture.

Harness expectations

Three classes of install/runtime behaviour look like package bugs and are host-harness behaviour the package cannot control: sibling-plugin namespaces, deferred tools surfaced via ToolSearch and cross-scope skill drift. Diagnostics and the package's response: docs/contracts/harness-expectations.md. When a skill appears twice, start with 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

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

Beyond software

The same orchestration core drives non-software trades via 5-minute scaffold.

Data governance & domain safety

Three domain-safety rules (decision-trace-v1.

Code provenance & license governance

Every diff is checked against a license policy derived from the target repo's own detected license (precedence-ordered; sources disagree → escalate, never guess) and a strict linter over our borrow ledger (docs/THIRD-PARTY-NOTICES.md) that fails a deny-class or unknown license, a missing transformation note or a rename-only-phrased one — wired into ci/ci-strict. license-compliance-audit runs a similarity scan on demand, invoked by a human and never by a pipeline. This is provenance-governed borrow discipline with an audited 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 log of skills, rules and commands consulted in /implement-ticket / /work. Enable via telemetry.artifact_engagement.enabled: true; JSONL in the project, nothing uploaded. Reports: npx @event4u/agent-config telemetry:report.

Context-aware command suggestion

A prompt matching a command's purpose ("setze ticket ABC-123 um" → /implement-ticket) surfaces it as a numbered option — 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
• Governed runtime — resident processes require supervision, scoped writes and a stop control

Documentation

Browse content: 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.

Upgrade and staleness symptoms — a command or skill missing after an upgrade, skills appearing twice, an interrupted upgrade, command not found, stale project files: docs/troubleshooting.md § Upgrade and staleness.

Development

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

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: submission checklist).

Requirements

• Node ≥ 22.6 — 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

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