@event4u/agent-config 1.9.1

package/README.md

@@ -0,0 +1,357 @@
+# Agent Config — Governed Agent System
+
+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.
+
+<p align="center">
+  <strong>124 Skills</strong> · <strong>44 Rules</strong> · <strong>67 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
+</p>
+
+---
+
+## 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:
+
+```bash
+# 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:
+
+```bash
+# 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](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](docs/installation.md)
+
+**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](docs/getting-started.md)
+
+---
+
+## 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](.agent-src/commands/implement-ticket.md) ·
+  [Flow contract](agents/contexts/implement-ticket-flow.md)
+
+---
+
+## 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](https://agentskills.io).
+
+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/`](scripts/schemas/)
+([contract](agents/docs/frontmatter-contract.md)), 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 →](docs/customization.md)
+
+> **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`](.agent-src/skills/laravel/SKILL.md) | Write Laravel code following framework conventions and project architecture |
+| [`pest-testing`](.agent-src/skills/pest-testing/SKILL.md) | Write Pest tests with clear intent, good coverage, and project conventions |
+| [`eloquent`](.agent-src/skills/eloquent/SKILL.md) | Eloquent models, relationships, scopes, eager loading, type safety |
+| [`create-pr`](.agent-src/commands/create-pr.md) | Create GitHub PRs with structured descriptions from Jira tickets |
+| [`commit`](.agent-src/commands/commit.md) | Stage and commit changes following Conventional Commits |
+| [`fix-ci`](.agent-src/commands/fix-ci.md) | Fetch CI errors from GitHub Actions and fix them |
+| [`fix-pr-comments`](.agent-src/commands/fix-pr-comments.md) | Fix and reply to all open review comments on a PR |
+| [`quality-fix`](.agent-src/commands/quality-fix.md) | Run PHPStan/Rector/ECS and fix all errors |
+| [`bug-analyzer`](.agent-src/skills/bug-analyzer/SKILL.md) | Root cause analysis from Sentry errors or Jira tickets |
+| [`improve-before-implement`](.agent-src/rules/improve-before-implement.md) | Challenge weak requirements before coding |
+| [`docker`](.agent-src/skills/docker/SKILL.md) | Dockerfile, docker-compose, container management |
+| [`security`](.agent-src/skills/security/SKILL.md) | Auth, policies, CSRF, rate limiting, secure coding |
+| [`api-design`](.agent-src/skills/api-design/SKILL.md) | REST conventions, versioning, deprecation |
+| [`database`](.agent-src/skills/database/SKILL.md) | MariaDB optimization, indexing, query performance |
+
+→ [Browse all skills](docs/skills-catalog.md) · [llms.txt](llms.txt)
+
+---
+
+## Featured Commands
+
+| Command | What it does |
+|---|---|
+| [`/commit`](.agent-src/commands/commit.md) | Stage and commit with Conventional Commits |
+| [`/create-pr`](.agent-src/commands/create-pr.md) | Create PR with Jira-linked description |
+| [`/fix-ci`](.agent-src/commands/fix-ci.md) | Fetch and fix GitHub Actions failures |
+| [`/fix-pr-comments`](.agent-src/commands/fix-pr-comments.md) | Fix and reply to review comments |
+| [`/quality-fix`](.agent-src/commands/quality-fix.md) | Run and fix all quality checks |
+| [`/review-changes`](.agent-src/commands/review-changes.md) | Self-review before creating a PR |
+| [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
+| [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
+
+→ [Browse all 67 commands](.agent-src/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 &nbsp; — = not available &nbsp; ☑️ = 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 + 67 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 →](docs/installation.md#augment-cli) |
+| **Claude Code** | ✅ | ✅ | ✅ | [Install →](docs/installation.md#claude-code) |
+| **Copilot CLI** | ✅ | ✅ | ✅ | [Install →](docs/installation.md#copilot-cli) |
+
+Skills use a `SKILL.md` format with YAML frontmatter that is compatible with
+the [Agent Skills](https://agentskills.io) 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**](docs/getting-started.md) | First run, 3-test experience, profiles, next steps |
+| [**Installation**](docs/installation.md) | Plugin setup, Composer/npm, Git submodule, orchestrator details |
+| [**Architecture**](docs/architecture.md) | System layers, content pipeline, tool support matrix |
+| [**Development**](docs/development.md) | Prerequisites, editing workflow, all `task` commands, project structure |
+| [**Customization**](docs/customization.md) | Overrides, AGENTS.md, agent settings, cost profiles |
+| [**Quality & CI**](docs/quality.md) | Linting, CI pipeline, compression system |
+
+Uninstalling: see
+[docs/installation.md#uninstalling](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:
+
+```bash
+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**](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](https://taskfile.dev/) — runs the CI pipeline (`task ci`).
+- No runtime dependencies — the package ships static markdown files.
+
+## License
+
+[MIT](LICENSE) — you can use, fork, and redistribute this freely.

package/bin/install.php

@@ -0,0 +1,38 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Agent Config — Project Installer (Composer wrapper)
+ *
+ * Thin wrapper that delegates to scripts/install, the primary orchestrator.
+ * The orchestrator chains payload sync (install.sh) and bridge generation
+ * (install.py); this wrapper only exists so that PHP/Composer users can
+ * invoke it via `php vendor/bin/install.php` without knowing about bash.
+ *
+ * Usage:
+ *   php vendor/bin/install.php                     # full install
+ *   php vendor/bin/install.php --profile=balanced  # pick cost profile
+ *   php vendor/bin/install.php --force             # overwrite existing bridges
+ *   php vendor/bin/install.php --skip-bridges      # payload only
+ *   php vendor/bin/install.php --skip-sync         # bridges only
+ *   php vendor/bin/install.php --help              # full option list
+ */
+
+$packageRoot = dirname(__DIR__);
+$installer = $packageRoot . '/scripts/install';
+
+if (! file_exists($installer)) {
+    fwrite(STDERR, "  ❌  Installer script not found: {$installer}\n");
+    exit(1);
+}
+
+// Forward all CLI arguments to the bash orchestrator. Drop $argv[0] (this script).
+$forwarded = array_slice($argv, 1);
+$command = array_merge(['bash', $installer], $forwarded);
+$escaped = array_map('escapeshellarg', $command);
+
+$exitCode = 0;
+passthru(implode(' ', $escaped), $exitCode);
+exit($exitCode);

package/composer.json

@@ -0,0 +1,29 @@
+{
+    "name": "event4u/agent-config",
+    "description": "Shared agent configuration — skills, rules, commands, guidelines, and templates for AI coding tools",
+    "type": "library",
+    "license": "MIT",
+    "require": {
+        "php": ">=8.0"
+    },
+    "bin": [
+        "bin/install.php"
+    ],
+    "archive": {
+        "exclude": [
+            "/.agent-src.uncompressed",
+            "/.compression-hashes.json",
+            "/agents",
+            "/tests",
+
+            "/Taskfile.yml",
+            "/.github",
+            "/.idea",
+            "/.claude",
+            "/.cursor",
+            "/.clinerules",
+            "/.windsurfrules",
+            "/GEMINI.md"
+        ]
+    }
+}

package/config/agent-settings.template.yml

@@ -0,0 +1,96 @@
+# Agent Settings
+# This file is generated by scripts/install.py from
+# config/agent-settings.template.yml. It holds personal and project-wide
+# preferences. Run /config-agent-settings to re-sync it against the
+# template at .augment/templates/agent-settings.md.
+
+# --- Cost profile ---
+#
+# Selects which agent surfaces are active. See docs/customization.md for
+# the authoritative description.
+#
+# minimal  = rules, skills, and commands only (zero extra surface, default)
+# balanced = + runtime dispatcher for skills that declare a shell command
+# full     = + tool adapters (GitHub / Jira, read-only, opt-in)
+# custom   = ignore profile — every matrix value must be set explicitly
+cost_profile: __COST_PROFILE__
+
+# --- Personal preferences ---
+personal:
+  # IDE to use for opening files (code, phpstorm, cursor, …)
+  # Empty = agent will not auto-open files; fill in once if you want that.
+  ide: ""
+
+  # Automatically open edited files in the IDE (true, false)
+  open_edited_files: false
+
+  # User's first name — used to address the user personally
+  user_name: ""
+
+  # rtk (Rust Token Killer) installed for output filtering (true, false)
+  # Agent will auto-detect and ask once, then store the result
+  rtk_installed: false
+
+  # Minimal output mode (true, false)
+  # true  = short bullet points during work, concise summary at the end
+  # false = verbose explanations and reasoning
+  minimal_output: true
+
+  # Play-by-play mode (true, false)
+  # true  = briefly share intermediate findings as you go
+  # false = silently investigate, only report the conclusion
+  play_by_play: false
+
+# --- Project / team preferences ---
+project:
+  # Prefix PR comment replies with a bot icon 🤖 (true, false)
+  pr_comment_bot_icon: false
+
+  # Path to the PR template file (relative to project root)
+  pr_template: .github/pull_request_template.md
+
+  # Target repository for universal improvement PRs (e.g. org/agent-config)
+  upstream_repo: ""
+
+  # Branch prefix for improvement PRs
+  improvement_pr_branch_prefix: "improve/agent-"
+
+# --- GitHub integration ---
+github:
+  # API method for replying to PR review comments
+  # replies_endpoint      = POST /pulls/comments/{id}/replies (preferred)
+  # create_review_comment = POST /pulls/{number}/reviews (fallback)
+  # auto                  = detect on first use and update this setting
+  pr_reply_method: create_review_comment
+
+# --- Eloquent (Laravel) ---
+eloquent:
+  # Model property access style
+  # getters_setters  = strict typed getters/setters, getAttribute() only inside model
+  # get_attribute    = use getAttribute()/setAttribute() everywhere
+  # magic_properties = use $model->column_name (Laravel default)
+  access_style: getters_setters
+
+# --- Optional pipelines ---
+pipelines:
+  # Skill improvement pipeline (true, false)
+  # true  = after meaningful tasks, propose learning capture and improvements
+  # false = silent, no post-task analysis
+  skill_improvement: false
+
+# --- Subagent orchestration ---
+#
+# Controls model selection and parallelism for subagent-based workflows
+# (/do-and-judge, /do-in-steps, /judge). Empty values fall back to the
+# runtime defaults described in .augment/contexts/subagent-configuration.md.
+subagents:
+  # Model for implementer subagents (empty = same tier as the session model)
+  implementer_model: ""
+
+  # Model for judge subagents
+  # (empty = one tier above implementer: opus if sonnet, sonnet if haiku)
+  judge_model: ""
+
+  # Maximum number of parallel subagent invocations
+  # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
+  max_parallel: 3

package/config/profiles/balanced.ini

@@ -0,0 +1,10 @@
+; Agent Config — Profile: balanced
+; Best for: teams that want to run skills programmatically via the
+; runtime dispatcher
+; Token overhead: low
+;
+; Adds the runtime dispatcher on top of minimal, so skills that declare
+; a shell command can be invoked via scripts/runtime_dispatcher.py.
+; See docs/customization.md for the full profile description.
+
+cost_profile=balanced

package/config/profiles/full.ini

@@ -0,0 +1,10 @@
+; Agent Config — Profile: full
+; Best for: platform teams that want read-only access to GitHub / Jira
+; from skills and commands
+; Token overhead: moderate
+;
+; Adds experimental tool adapters on top of balanced. Adapters are
+; read-only and opt-in per call. See docs/customization.md for the full
+; profile description.
+
+cost_profile=full

package/config/profiles/minimal.ini

@@ -0,0 +1,10 @@
+; Agent Config — Profile: minimal
+; Best for: new users, solo developers, first-time adoption
+; Token overhead: zero extra surface
+;
+; Default profile. Ships rules, skills, and commands only — no runtime
+; dispatcher, no tool adapters. See docs/customization.md for the full
+; profile description. scripts/install.py merges this file with
+; config/agent-settings.template.ini to produce the user's .agent-settings.
+
+cost_profile=minimal