README

Agent Config — every claim machine-checked, including the 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 on a drift of one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: Commands 202 counts every command file recursively (the linked directory holds 61 at its top level), and Rules 121 counts the source rules while the linked projection holds 120 — 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 — 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). Resident processes are permitted only under the supervision contract ADR-249 establishes — a policy this repository adopted on 2026-08-27, 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

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? The full suite installs in 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 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 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 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 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.

Profile	Audience	Experience page
👩‍💻 `developer`	IC engineer	page
✍️ `content_creator`	Writers, ghostwriters, marketers	page
🚀 `founder`	Solo / early-stage founder	page
🏛 `agency`	Multi-client delivery shop	page
💼 `finance`	CFO / fractional finance / FP&A	page
🛡 `ops`	RevOps, support, SRE-adjacent	page

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:

Flow	Start with	The journey
🔍 Discovery	`/feature:plan` · `/research`	explore → plan → estimate → refine, before building
🔨 Implementation	`/work` · `/implement-ticket`	plan → implement → verify → commit
🔎 Review	`/review-changes` · `/judge`	self-review → judge → quality-fix → threat-model
🚢 Delivery	`/commit` · `/pr:create`	commit in chunks → open PR → answer review

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

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

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.

# 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 on CI, a non-TTY, a headless host, or any CLI-mode flag, and 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: docs/wizard.md · 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, and 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 (ADR-020, 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. 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.

In scope	Out of scope
Skills, rules, commands, guidelines, personas	Agent loop / LLM dispatcher
Multi-tool projection + condensation pipeline	Execution engine inside the package
Memory helpers (`memory-add`, `memory-promote`)	Cross-tool observability dashboard
Linters, CI, frontmatter validation against JSON-Schema (contract)	Runtime GUI / web dashboard
Skill orchestration via citations + deterministic helpers	Opinionated automatic skill-resolver (ML / relevance ranking that decides for you)
User-driven projection-time filtering by profile + packs (ADR-040)	A runtime resolver / daemon (mid-session switching — conditional, post-6.0.0)

What your agent is asked to do

Default behavior	With agent-config
Guess and edit blindly	Analyze code before changing it
Drift from project conventions	Follow detected stack conventions
Skip or invent tests	Write tests in the project's framework
Generic commit messages	Conventional Commits with scope + ticket links
Skip quality checks	Run the project's quality pipeline and fix reported errors
Open PRs without context	Structured PR descriptions from Jira / Linear / GitHub
Claim "done" without proof	Verify with real execution before claiming done

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:

Band	Score	Action
high	`≥ 0.8`	Silent proceed — AC + assumptions in the report
medium	`0.5–0.79`	Halts with assumptions report; confirm or edit
low	`< 0.5`	Halts with one clarifying question on the weakest dimension

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.

Profile	What you get	When to pick it
`minimal`	Non-negotiable safety floor only. Cheapest, fastest.	Quick questions · throw-away scripts · CI · tight token budgets
`balanced` (default)	Safety floor + everyday coaching (sensible defaults, review nudges, common pitfalls).	Day-to-day work
`full`	Everything, including long-tail rules normally only maintainers need.	Working on `agent-config` itself · audits · max-fidelity demos

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

Primitive	Voice	Disclosure
`personas/*.md`	Review-lens (internal critique)	n/a
`.agent-user.md` (project root, gitignored)	The maintainer's own voice — `/post-as:me`	None (you are the author)
`agents/reference/ghostwriter/<slug>.md` (gitignored)	Documented public figure — `/post-as:ghostwriter`	Mandatory, non-removable footer

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

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

Shape	Status	Path
Single-user workspace	✅ today	`npx @event4u/agent-config init` — single machine, single user; no remote sync
Small team (3–10 people)	✅ today	Shared `agents/overrides/` Git repo + shared NAS for knowledge — no code change, no new server. Recipe: `docs/deploy/small-team-recipe.md`
Organization mode (SSO · central policy · team context · internal connectors)	⏸ not started	Each shape gated on a recruited customer + funded audit + maintainer ADR. Posture rationale: `docs/deploy/team-deployment-posture.md`

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`)

Tool	Rules	Skills	Commands	How it works
Claude Code	✅	✅	✅	Reads `.claude/`
Cursor	✅	—	☑️	Reads `.cursor/rules/` + commands via AGENTS.md
Cline	✅	—	☑️	Reads `.clinerules/` + commands via AGENTS.md
Windsurf	✅	—	☑️	Reads `.windsurfrules` + commands via AGENTS.md
Gemini CLI	✅	—	☑️	Reads `GEMINI.md`
GitHub Copilot	✅	—	☑️	Reads `.github/copilot-instructions.md`
Roo Code	✅	—	☑️	Auto-discovers `.roo/rules/*.md` + AGENTS.md
Codex CLI	✅	—	☑️	Auto-discovers `AGENTS.md`
Continue.dev	✅	—	☑️	Auto-discovers `.continue/rules/*.md` + AGENTS.md
Aider	📌	—	—	Manual `read:` in `.aider.conf.yml`
Augment (VSCode/IntelliJ)	📌	—	—	Global-only; project writes marker
Claude Desktop	📌	—	—	Global-only

✅ 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)

Tool	Install
Augment CLI · Copilot CLI	Install → — rules + skills + commands, marketplace-updated

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

Command	What it does
`agent-config init`	One-shot install — opens the browser wizard (recommended path or step-by-step)
`agent-config init --project`	Initialize a project: minimal `agents/` bridge + managed `.gitignore` block
`agent-config config`	Open the configuration GUI — global settings hub (simple + advanced tiers, search, reset-to-default)
`agent-config config --project`	Open the project configuration surface
`agent-config setup`	Re-run the guided onboarding wizard (prefilled from your current state)
`agent-config upgrade`	Update the global install to the latest release + additively sync settings
`agent-config doctor`	Read-only health/drift report

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:

Stack	Coverage
Laravel · modern PHP (deepest)	Pest · PHPStan · Rector · ECS · Eloquent · Livewire/Flux · Horizon · Pulse · Reverb · Pennant
Symfony	`symfony-workflow` (DI · Doctrine · Messenger · voters · Twig) + project-analysis
Next.js App Router	`nextjs-patterns` (RSC · Server Actions · caching · route handlers) + UI `react-shadcn`
Zend / Laminas	project-analysis + shared PHP coder/quality skills
React · Node / Express	project-analysis + UI `react-shadcn`
Vue · plain HTML	UI directive set (`vue` / `plain`)
Cross-stack	API design · testing · security · database · Docker · Git · CI · review · threat modeling · observability

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 (precedence-ordered; sources disagree → escalate, never guess) and a strict linter over our borrow ledger (provenance/borrows.jsonl → 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 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
Governed runtime — resident processes require supervision, scoped writes, and a stop control

Documentation

Document	Content
Getting Started	First run, 3-test experience, profiles, next steps
Installation	All install paths, Composer/npm, orchestrator details
Architecture	System layers, content pipeline, tool support matrix
Customization	Overrides, AGENTS.md, agent settings, cost profiles
Quality & CI	Linting, CI pipeline, condensation system
Migration	Per-version upgrade steps
Showcase	More examples & expected behavior

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.

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:

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 throughout — CLI, UI, and the 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

event4u / agent-config

Package info

Security

Statistics