event4u/agent-config

Shared agent configuration — skills, rules, commands, guidelines, and templates for AI coding tools

1.12.0 2026-04-25 06:51 UTC

Requires

• php: >=8.0

MIT

README

Teach your AI agents Laravel, PHP, testing, Git workflows, and 120+ more skills — with quality guardrails built in.

Your agent learns to write Laravel code, run tests, create PRs, fix CI — and follows your team's coding standards while doing it.

124 Skills · 46 Rules · 73 Commands · 46 Guidelines · 8 AI Tools

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 the package: no Task, no Make, no build tools required. scripts/install orchestrates two stages: a bash payload sync and a Python bridge generator. Python 3 (stdlib only, pre-installed on macOS 12.3+ and all major Linux distros) is required for the bridge stage; without it the orchestrator warns, runs the payload sync, and continues. The package makes rules, skills, and commands available project-locally for all supported AI tools. Task is required for contributors who want to rebuild the compressed content locally — see CONTRIBUTING.md.

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:

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

→ Full getting started guide

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

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 PHP/Laravel coding standards
Skip or invent tests	Write Pest tests following the project's conventions
Write generic commit messages	Use Conventional Commits with scope and Jira links
Skip quality checks	Run PHPStan, Rector, ECS and fix reported errors
Open PRs without context	Produce structured PR descriptions from Jira 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

Start with Rules + Skills. Everything else is optional.

Mode	What's active	Token overhead
Minimal (default)	Rules, Skills, Commands	Zero
Balanced	+ Runtime dispatcher for skills that declare a shell command	Low
Full	+ Tool adapters (GitHub / Jira read-only, opt-in)	Moderate

Nothing runs automatically without your control. Configure modes →

Experimental modules: the runtime (dispatcher + shell handler) runs two pilot skills in CI (lint-skills, check-refs). The tool registry ships two read-only adapters (GitHub, Jira) behind the full profile. Other handlers (php, node) are still scaffold. The minimal profile — which most users should pick — is unaffected.

Who this is for

The content is built for PHP / Laravel teams and is where the package is most useful out of the box. Skills, rules, and quality-tool integration assume a Laravel-style repository (Pest, PHPStan, Rector, ECS, Artisan, Composer workflows). You can install it on any project, but:

Stack	Fit
Laravel / modern PHP	✅ Primary audience — most skills apply directly
Other PHP frameworks (Symfony, Zend/Laminas)	☑️ Deep-analysis skills apply; framework-specific ones do not
JavaScript / TypeScript / Next.js / Node	☑️ General skills + governance apply; PHP-specific skills are noise
Other stacks	⚠️ Cherry-pick rules/commands; expect to disable a lot

A language-agnostic core is on the roadmap but not yet extracted. If you adopt the package outside the primary audience, please 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

→ Browse all skills · 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
/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 73 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 + 124 skills + 73 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.

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

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

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

Development

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

task sync          # Sync non-.md files
task ci            # Run all CI checks
task test          # Run all tests
task lint-skills   # Lint skills, rules, commands

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

Requirements

To install the package into a consumer project:

• Bash — primary installer is scripts/install, orchestrating scripts/install.sh (payload sync) and scripts/install.py (bridges). Available on macOS, Linux, and WSL.
• Python 3.10+ — required for the bridge stage only. Pre-installed on macOS 12.3+ and all major Linux distros. If missing, the orchestrator skips bridges and completes the payload sync.
• Composer or npm — to pull the package itself.

Platform support:

Platform	Status
macOS 12.3+	✅ Supported
Linux (modern distros)	✅ Supported
Windows (WSL2)	✅ Supported
Windows (Git Bash)	⚠️ Works; symlinks need Developer Mode
Windows (native PowerShell/cmd)	❌ Not supported

For contributors only (rebuilding .augment/ locally):

• Task — runs the CI pipeline (task ci).
• No runtime dependencies — the package ships static markdown files.

License

MIT — you can use, fork, and redistribute this freely.