README

agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.

Give your AI agents an audit-disciplined orchestration contract — testing, Git, CI, code review, and 120+ stack-aware skills — with quality guardrails built in.

Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).

144 Skills · 60 Rules · 103 Commands · 59 Guidelines · 8 AI Tools

Start here

Three ways in, depending on what you're doing today:

Path	Audience	What it does
`/onboard`	New user, fresh install	Captures name, IDE, rtk, and cost profile; sets `onboarding.onboarded=true`
`task ci`	Contributor working on this package	Runs the full sync + lint + test pipeline; must be green before push
`task generate-tools`	Multi-agent user / consumer project	Rebuilds `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` from the source

If none of those apply yet — start with the Quickstart and pick a path once it's installed.

Quickstart

Two minutes from composer require to a better-behaved agent.

For teams (recommended)

Install once in the project — available to everyone who works on it:

# PHP
composer require --dev event4u/agent-config

# JavaScript/TypeScript
npm install --save-dev @event4u/agent-config

After installing the package, run the installer to sync the payload and create .agent-settings.yml, .vscode/settings.json, .augment/settings.json, and the tool-specific glue:

# PHP / Composer projects — explicit step (Composer does not auto-run it):
php vendor/bin/install.php
# or directly (any environment):
bash vendor/event4u/agent-config/scripts/install

# npm projects run the installer automatically via postinstall.
# To re-run or override the default profile:
bash node_modules/@event4u/agent-config/scripts/install --profile=balanced

To install: no Task / Make / build tools — scripts/install runs a bash payload sync plus a Python 3 bridge generator (stdlib only, default on macOS 12.3+ / major Linux distros). Python missing → orchestrator warns and continues payload-only. Task is needed only for contributors rebuilding compressed content — see CONTRIBUTING.md.

Verify hook coverage after installing — every supported platform (Augment, Claude Code, Cowork, Cursor, Cline, Windsurf, Gemini CLI, Copilot fallback) is wired through one universal dispatcher per hook-architecture-v1 (beta). Run ./agent-config hooks:status for the matrix (--strict for CI, --format json for tooling). The installer also dry-fires the dispatcher per bridge as a post-install smoke test (skip: --no-smoke).

For individual use (optional)

Install directly in your agent for global, cross-project use:

Tool	Install
Augment CLI	`auggie plugin install agent-config@event4u-agent-config`
Claude Code	`claude plugin install agent-config@event4u-agent-config`
Copilot CLI	`copilot plugin install agent-config@event4u-agent-config`

→ All install options & project bridge setup

Open your agent and try these 3 prompts:

"Refactor this function" → watch: agent analyzes first
"Add caching to this" → watch: agent asks instead of guessing
"Implement this feature" → watch: agent respects your codebase

→ Full getting started guide · More examples & expected behavior

Optional: persistent agent memory

agent-config integrates with @event4u/agent-memory — an MCP-based memory backend that gives agents persistent learnings across sessions. It is strictly optional:

Not a required dependency (declared as suggest in Composer and as an optional peer in npm). agent-config itself never imports it.
Without it, agent skills fall back to file-based memory under agents/memory/ and continue to work normally.
Recommended for teams that want learnings to survive across machines, branches, and chat sessions.

Install in the same project (dev-only):

npm install --save-dev @event4u/agent-memory

→ Memory contract & retrieval API (beta)

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.
Runs tests (targeted first, full suite on success).
Reviews the diff through four judges (bugs, security, tests, code quality).
Reports a copyable markdown block with changes, verdicts, and follow-ups — then stops. /commit and /create-pr are suggestions, never run automatically.

If any step hits ambiguity, the flow halts with numbered options so you decide — never a silent guess. Persona comes from .agent-settings.yml (roles.active_role): senior-engineer (default), qa (widens to the full test suite), or advisory (plan-only, skips implementation).

→ Command reference · Flow contract (beta)

Sibling entrypoint: `/work` (free-form prompt)

Same engine, different envelope. Use /work when you have a goal but no ticket yet:

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

The first pass scores the prompt on five dimensions (goal_clarity, scope_boundary, ac_evidence, stack_data, reversibility) and routes on the resulting band:

Band	Score	Engine action
high	`≥ 0.8`	Silent proceed — reconstructed AC + assumptions land in the delivery report
medium	`0.5–0.79`	Halts with assumptions report; you confirm or edit before plan
low	`< 0.5`	Halts with one clarifying question on the weakest dimension

After the band gate releases, the rest of the flow is identical to /implement-ticket. UI-shaped prompts are routed through the product UI track — see below.

→ Command reference · refine-prompt skill · ADR

Pick which one: ticket id or pasted ticket payload → /implement-ticket. Free-form goal, no ticket → /work. The two share .work-state.json and refuse to switch envelopes mid-flight.

Product UI track

UI-shaped work (build a screen, improve a component, fix microcopy) switches the engine to one of three directive sets:

`directive_set`	When	Flow
`ui`	Non-trivial UI surface	`audit → design → apply → review → polish → report`
`ui-trivial`	Bounded edit (≤ 1 file, ≤ 5 changed lines)	`apply → test → report`
`mixed`	Backend + UI	`contract → ui → stitch`

Four load-bearing properties: (1) existing-UI audit is a hard gate — no apply without audit, enforced at dispatcher AND ui-audit-gate rule; (2) design brief is locked microcopy — placeholders (<placeholder>, Lorem, TODO:) rejected at both ends; (3) polish has a 2-round ceiling, then halts ship-as-is / abort / hand-off; (4) a11y precedence — unresolved axe-core / pa11y violations must be fixed or explicitly accepted before ship, regardless of round counter (one-shot extension allowed). The engine never renders UI itself: rendering happens out-of-process, the engine consumes a preview_envelope (status / screenshots / findings) via a defined contract. Stack detection routes (composer.json + package.json) to blade-livewire-flux / react-shadcn / vue / plain; trivial path reclassifies loudly when preconditions fail. Halt budget on the happy path is 2.

→ Mental model (1 page — when each set, where it stops, what the agent must never do) · Flow contract (beta) · ADR · Stack-extension recipe (beta)

What your agent is asked to do

The package ships rules and skills that guide the agent toward these behaviors. The agent still decides in the moment, so the table is a description of intent — not a guarantee of output.

Default behavior	With agent-config (the agent is instructed to)
Guess and edit blindly	Analyze code before changing it — no blind edits
Drift from project conventions	Follow the project's coding standards (detected from the stack)
Skip or invent tests	Write tests in the project's framework (Pest, PHPUnit, Vitest, Jest, …)
Write generic commit messages	Use Conventional Commits with scope and ticket links
Skip quality checks	Run the project's quality pipeline (PHPStan/Rector/ECS, ESLint/Prettier/tsc, …) and fix reported errors
Open PRs without context	Produce structured PR descriptions from Jira / Linear / GitHub tickets
Claim "done" without proof	Verify with real execution before claiming "done"

What this package is — and what it isn't

agent-config is a content layer — skills, rules, commands, and guidelines — distributed via Composer and 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 Code, Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot). Think of this package as a playbook and style guide for those tools — not a replacement for them.

In scope	Out of scope
Skills, rules, commands, guidelines	Agent loop / LLM dispatcher
Multi-tool projection + compression pipeline	Execution engine inside the package
Memory helpers (`memory-add`, `memory-promote`, query scripts)	Cross-tool observability dashboard
Linters, CI, frontmatter validation	Runtime GUI / web dashboard
Skill orchestration via markdown citations + deterministic helpers	Opinionated skill-resolver algorithm

Frameworks like LangChain or CrewAI are runtimes; this package sits one layer above them — it tells whichever agent you already use 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/ (contract), enforced by task validate-schema in CI. Runtime validation inside a live agent session is explicitly not.

You don't need everything

cost_profile is the master switch for rule-tier loading. The kernel (always-loaded Iron-Law floor, ≤ 26k chars across 9 rules) ships in every profile; tier-1 and tier-2 rules are gated by profile and resolved at session start from router.json.

Profile	Rule tiers loaded	Token footprint	Best for
`minimal`	kernel only (no router, no auto-rules)	lowest	Cost-sensitive sessions; trivial Q&A; CI runs
`balanced` (default)	kernel + tier-1 auto-rules	medium	Day-to-day work — current behaviour superset
`full`	kernel + tier-1 + tier-2 (everything)	highest	Agent-config development; full rule fidelity

Architecture: docs/contracts/rule-router.md (beta) · kernel set: docs/contracts/kernel-membership.md (beta) · Configure profiles →

Stability tiers — STABILITY.md for the full matrix. Runtime Dispatcher: stable (php / node handlers scaffold). Work Engine: beta (beta) — orchestrator behind /work

/implement-ticket. Tool Adapters: experimental, read-only, behind full. minimal profile unaffected.

Who this is for

agent-config ships a stack-agnostic governance core (orchestration contract, role modes, command clusters, quality gates, audit-discipline) plus parallel stack-specific skill sets at varying depth:

Stack	Coverage
Laravel · modern PHP	Skills, rules, project-analysis, quality-tool wiring (Pest · PHPStan · Rector · ECS)
Symfony · Zend / Laminas	Project-analysis skills + shared PHP coder/quality skills
Next.js · React · Node / Express	Project-analysis skills + UI directive set (`react-shadcn`)
Vue · plain HTML	UI directive set (`vue` / `plain`) — analysis skills as they ship
Cross-stack	API design · testing · security · database · Docker · Git · CI · review · threat modeling · observability

Deepest reference stack today: Laravel. Skill density covers Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant — the stack the package was first proven on. Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.

Featured Skills

Skill	What your agent learns
`laravel`	Write Laravel code following framework conventions and project architecture
`pest-testing`	Write Pest tests with clear intent, good coverage, and project conventions
`eloquent`	Eloquent models, relationships, scopes, eager loading, type safety
`create-pr`	Create GitHub PRs with structured descriptions from Jira tickets
`commit`	Stage and commit changes following Conventional Commits
`/fix ci`	Fetch CI errors from GitHub Actions and fix them
`/fix pr-comments`	Fix and reply to all open review comments on a PR
`quality-fix`	Run PHPStan/Rector/ECS and fix all errors
`bug-analyzer`	Root cause analysis from Sentry errors or Jira tickets
`improve-before-implement`	Challenge weak requirements before coding
`docker`	Dockerfile, docker-compose, container management
`security`	Auth, policies, CSRF, rate limiting, secure coding
`api-design`	REST conventions, versioning, deprecation
`database`	MariaDB optimization, indexing, query performance

→ Public catalog (all rules, skills, commands, guidelines) · Skills only · llms.txt

Featured Commands

Command	What it does
`/commit`	Stage and commit with Conventional Commits
`/create-pr`	Create PR with Jira-linked description
`/fix ci`	Fetch and fix GitHub Actions failures
`/fix pr-comments`	Fix and reply to review comments
`/optimize skills`	Audit skills, find duplicates, run linter
`/feature plan`	Interactively plan a feature
`/quality-fix`	Run and fix all quality checks
`/review-changes`	Self-review before creating a PR
`/jira-ticket`	Read ticket from branch, implement feature
`/compress`	Compress skills for token efficiency

→ Browse all 103 active commands

Supported Tools

Project-installed (Composer / npm)

Every developer gets the same behavior. No per-user setup needed.

Tool	Rules	Skills	Commands	How it works
Augment VSCode/IntelliJ	✅	✅	✅	Reads `.augment/` from project
Claude Code	✅	✅	✅	Reads `.claude/` (skills + commands as skills)
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` (includes commands reference)
GitHub Copilot	✅	—	☑️	Reads `.github/copilot-instructions.md` (includes commands)

✅ = native support — = not available ☑️ = text reference only (commands are listed in AGENTS.md, but the tool cannot invoke them as native slash-commands)

What this means in practice: Augment Code and Claude Code get the full package (rules + 144 skills + 103 native commands). Cursor, Cline, Windsurf, Gemini CLI, and GitHub Copilot only get the rules natively; skills and commands are available to them as documentation the agent can read, not as first-class features.

Plugin-installed (optional, for global use)

Works across all your projects. Auto-updates via marketplace.

Tool	Rules	Skills	Commands	Install
Augment CLI	✅	✅	✅	Install →
Claude Code	✅	✅	✅	Install →
Copilot CLI	✅	✅	✅	Install →

Skills use a SKILL.md format with YAML frontmatter that is compatible with the Agent Skills community spec and with Claude Code's Agent Skills specification.

Cloud / Hosted-agent surfaces (paste-in or upload)

For platforms where the package's scripts cannot run, the package builds artefacts you upload or paste into the platform's own surface.

Surface	Output	How to install
Linear AI (Codegen, Charlie, …)	`dist/linear/{workspace,team,personal}.md`	Install →
Claude.ai Web Skills	`dist/cloud/<skill>.zip`	Install →

The Linear digest is split into three layers — workspace (universal coding posture), team (framework-specific), personal (empty stub). See docs/contracts/linear-ai-three-layers.md (beta) for the rationale and docs/contracts/linear-ai-rules-inclusion.md (beta) for the per-rule routing.

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
Terse-by-default chat output — verbosity flags off, intent narration off, caveman-speak prose-only — flip back via docs/customization.md § Verbosity

Documentation

Document	Content
Getting Started	First run, 3-test experience, profiles, next steps
Installation	Plugin setup, Composer/npm, Git submodule, orchestrator details
Architecture	System layers, content pipeline, tool support matrix
Development	Prerequisites, editing workflow, all `task` commands, project structure
Customization	Overrides, AGENTS.md, agent settings, cost profiles
Quality & CI	Linting, CI pipeline, compression system
Migration	Per-version upgrade steps (e.g. `implement_ticket → work_engine` in 1.15.0)

Uninstalling: see docs/installation.md#uninstalling — there is no dedicated uninstall command; removal is a documented manual step (package manager + rm -rf of generated dirs).

Maintainer telemetry (opt-in, default-off)

A local-only artefact-engagement log can be enabled by maintainers to see which skills, rules, commands, and guidelines the agent actually consults and applies during a /implement-ticket or /work run. The log is a JSONL file under the project root; nothing is uploaded, nothing is shared across projects. Default is off; consumers see no prompts.

# .agent-settings.yml — opt in only when you want measurement
telemetry:
  artifact_engagement:
    enabled: true

Reports: ./agent-config telemetry:report. Full contract, privacy/redaction floor, and quartile semantics: contexts/contracts/artifact-engagement-flow.md (beta).

Context-aware command suggestion

When a user prompt matches a command's purpose ("setze ticket ABC-123 um" → /implement-ticket), the agent surfaces matches as a numbered-options block with an always-present "run the prompt as-is" escape. Nothing auto-executes — the user picks every time. Three opt-out paths:

# .agent-settings.yml
commands:
  suggestion:
    enabled: true            # global on/off
    blocklist: []            # specific commands never suggested
    confidence_floor: 0.6    # tunable per command in frontmatter

Per-conversation: /command-suggestion-off disables the layer until re-enabled or the chat ends. Full scoring contract and hardening: adr-command-suggestion, command-suggestion-flow (beta).

Development

Edit in .agent-src.uncompressed/, compress, verify:

task ci            # Run all CI checks
task test          # Run all tests

→ Full commands and project structure: docs/development.md

Requirements

Bash — scripts/install orchestrates payload sync (install.sh) and bridges (install.py).
Python 3.10+ — bridge stage only; missing → orchestrator skips bridges.
Composer or npm — to pull the package.
Platform: macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks; native PowerShell / cmd unsupported. Contributors rebuilding .augment/ also need Task.

License

MIT.

event4u / agent-config

Maintainers

Package info

Statistics

Security

README

Start here

Quickstart

For teams (recommended)

For individual use (optional)

Optional: persistent agent memory

2-minute demo: `/implement-ticket`

Sibling entrypoint: `/work` (free-form prompt)

Product UI track

What your agent is asked to do

What this package is — and what it isn't

You don't need everything

Who this is for

Featured Skills

Featured Commands

Supported Tools

Project-installed (Composer / npm)

Plugin-installed (optional, for global use)

Cloud / Hosted-agent surfaces (paste-in or upload)

Core Principles

Documentation

Maintainer telemetry (opt-in, default-off)

Context-aware command suggestion

Development

Requirements

License

event4u / agent-config

Maintainers

Package info

Statistics

Security

README

Start here

Quickstart

For teams (recommended)

For individual use (optional)

Optional: persistent agent memory

2-minute demo: /implement-ticket

Sibling entrypoint: /work (free-form prompt)

Product UI track

What your agent is asked to do

What this package is — and what it isn't

You don't need everything

Who this is for

Featured Skills

Featured Commands

Supported Tools

Project-installed (Composer / npm)

Plugin-installed (optional, for global use)

Cloud / Hosted-agent surfaces (paste-in or upload)

Core Principles

Documentation

Maintainer telemetry (opt-in, default-off)

Context-aware command suggestion

Development

Requirements

License

2-minute demo: `/implement-ticket`

Sibling entrypoint: `/work` (free-form prompt)