@event4u/agent-config 1.9.1

package/docs/architecture.md

@@ -0,0 +1,144 @@
+# Architecture
+
+## System overview
+
+```
+Rules         → Behavior enforcement (always active)         ← stable
+Skills        → Execution logic (on-demand expertise)        ← stable
+Runtime       → Dispatcher + shell handler (pilot skills)    ← partial
+Tools         → External integrations (GitHub, Jira)         ← experimental
+```
+
+**Stable** = shipped, documented, exercised by the default (`minimal`) profile.
+**Experimental** = scaffold with tests and data model, but no real execution
+wired up yet.
+
+> The previous "observability, feedback, lifecycle" layers were removed in
+> 1.5 — they were scaffolds without production consumers. See the
+> [`archive/road-to-9.md`](../agents/roadmaps/archive/road-to-9.md) roadmap,
+> phase 4, for the rationale.
+
+## Content pipeline
+
+```
+.agent-src.uncompressed/          ← Source of truth (verbose, human-readable)
+    ↓ /compress command
+.agent-src/                     ← Compressed output (token-efficient, shipped in the package)
+    ↓ project_to_augment() — copies rules, symlinks rest
+.augment/                       ← Local projection for Augment Code (gitignored)
+    ↓ install.sh (Cursor, Cline, Windsurf, Augment VSCode) / plugin system
+.claude/ .cursor/ .clinerules/  ← Tool-specific symlinks/copies (auto-generated)
+.windsurfrules  GEMINI.md
+```
+
+## What's inside
+
+| Layer | Count | Purpose |
+|---|---|---|
+| **Skills** | 93 | On-demand expertise — Laravel, testing, Docker, API design, security, ... |
+| **Rules** | 31 | Always-active constraints — coding standards, scope control, verification |
+| **Commands** | 51 | Slash-command workflows — `/commit`, `/create-pr`, `/fix-ci`, `/compress`, ... |
+| **Guidelines** | 34 | Coding guidelines by language — PHP patterns, Eloquent, Playwright, ... |
+| **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
+| **Contexts** | 5 | Shared knowledge about the system itself |
+
+---
+
+## Layers
+
+### 1. Governance Layer
+
+- **Rules** → always-active behavior constraints
+- **Skills** → structured, executable procedures
+- **Guidelines** → reference-only documentation
+- **Commands** → workflow orchestration
+
+Ensures: no guessing, analysis before action, real verification, consistent outputs.
+
+### 2. Execution Layer (Runtime) — partially real, partially scaffold
+
+> **Status:**
+> - **Real:** shell-handler path — skills that declare an `execution.command`
+>   argv are dispatched and executed by `scripts/runtime_handler.py`. A typed
+>   `ExecutionResult` (exit code, stdout, stderr, duration, artifacts) is
+>   returned and can be persisted as JSON via `--output FILE`. Pilots:
+>   `lint-skills`, `check-refs`. Both run on every PR and appear in the
+>   GitHub Step Summary via `scripts/ci_summary.py`.
+> - **Scaffold:** `php` and `node` handlers — the frontmatter accepts them
+>   and the registry validates them, but no handler implementation exists
+>   yet.
+
+Skills opt into runtime by declaring execution metadata:
+
+```yaml
+execution:
+  type: manual | assisted | automated
+  handler: shell | php | node | internal | none
+  command:                       # required for shell/php/node runtime paths
+    - python3
+    - scripts/skill_linter.py
+    - "--all"
+  timeout_seconds: 120
+  allowed_tools: []
+  safety_mode: strict            # required for type=automated
+```
+
+Invoke a runtime-capable skill end-to-end:
+
+```bash
+python3 scripts/runtime_dispatcher.py run --skill lint-skills
+```
+
+The dispatcher resolves the skill, enforces safety constraints, then hands
+off to the matching handler. Environment is scrubbed to an explicit
+allowlist; `subprocess.run` is invoked with `shell=False` (argv only).
+
+Planned scope (still to come): `php` / `node` handlers, tool-registry
+wiring for `allowed_tools`, streaming output.
+
+### 3. Tool Integration — experimental
+
+> **Status: scaffold + read-only GitHub calls.** With a `GITHUB_TOKEN` the
+> GitHub adapter performs real read calls; without one it returns scaffold
+> data. Write operations (`create_pr`, `comment`, etc.) are scaffold only.
+> The Jira adapter is scaffold throughout.
+
+Controlled integration via adapters:
+
+- GitHub adapter (read-first: PRs, issues, files, commits)
+- Jira adapter (read-first: tickets, search)
+- Tool registry with safety rules for execution
+- Structured responses with error classification
+
+### 4. Cost Control
+
+> **Key principle:** Opt-in by default.
+
+The dispatcher and tool adapters activate only under the `balanced` or
+`full` profile. The default `minimal` profile ships rules, skills, and
+commands and nothing else. All settings and their profile defaults are
+documented in
+[`.agent-src.uncompressed/templates/agent-settings.md`](../.agent-src.uncompressed/templates/agent-settings.md).
+
+---
+
+## Supported AI Tools
+
+| Tool | Rules | Skills | Commands | Plugin | Method |
+|---|---|---|---|---|---|
+| **Augment CLI** | ✅ | ✅ | ✅ | ✅ | Native plugin (recommended) |
+| **Augment VSCode/IntelliJ** | ✅ | ✅ | ✅ | — | install.sh (copies + symlinks) |
+| **Claude Code** | ✅ | ✅ | ✅ | ✅ | Native plugin (recommended) |
+| **Copilot CLI** | ✅ | ✅ | ✅ | ✅ | Native plugin (recommended) |
+| **Cursor** | ✅ | — | — | — | install.sh (symlinks) |
+| **Cline** | ✅ | — | — | — | install.sh (symlinks) |
+| **Windsurf** | ✅ | — | — | — | install.sh (concatenated) |
+| **Gemini CLI** | ✅ | — | — | — | install.sh (symlink → AGENTS.md) |
+
+Skills use a `SKILL.md` format with YAML frontmatter, compatible with the
+[Agent Skills](https://agentskills.io) community spec and with Claude Code's
+Agent Skills specification.
+
+---
+
+← [Back to README](../README.md)

package/docs/customization.md

@@ -0,0 +1,88 @@
+# Customization
+
+## Override System
+
+The project override system allows consumer projects to extend or replace shared skills,
+rules, and commands **without modifying the package**.
+
+```
+agents/overrides/
+├── skills/                  ← Override skill behavior
+│   └── pest-testing/
+│       └── SKILL.md         ← Replaces .augment/skills/pest-testing/SKILL.md
+├── rules/                   ← Override rule behavior
+│   └── php-coding.md        ← Replaces .augment/rules/php-coding.md
+└── commands/                ← Override command behavior
+    └── commit/
+        └── SKILL.md
+```
+
+**Resolution order:** project override → shared package (`.augment/`).
+
+Overrides are project-specific and should be committed to the consumer project.
+Use the `/override-create` command to scaffold a new override.
+
+---
+
+## AGENTS.md
+
+Every consumer project should have an `AGENTS.md` at the project root.
+The installer copies a default version if none exists.
+
+`AGENTS.md` provides project-specific context to the agent: tech stack, conventions,
+module structure, test setup, and quality tooling.
+
+It is loaded by Claude Code, Augment Code, and Gemini CLI.
+
+---
+
+## Agent Settings
+
+The `.agent-settings.yml` file in the consumer project configures agent behavior.
+It is written as YAML with section-level grouping; dotted keys below reference
+those sections.
+
+### Available settings
+
+| Setting | Default | Description |
+|---|---|---|
+| `cost_profile` | `minimal` | Token budget (`minimal`, `balanced`, `full`, `custom`) |
+| `personal.user_name` | *(empty)* | User's first name for personalized responses |
+| `personal.minimal_output` | `true` | Suppress intermediate output |
+| `personal.play_by_play` | `false` | Share intermediate findings during analysis |
+| `personal.open_edited_files` | `false` | Open edited files in IDE |
+| `personal.ide` | *(empty)* | IDE for file opening (`cursor`, `code`, `phpstorm`) |
+| `pipelines.skill_improvement` | `false` | Enable post-task learning capture |
+
+### Cost profiles
+
+| Profile | Description |
+|---|---|
+| `minimal` | Zero extra surface. Rules, skills, and commands only. |
+| `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. |
+
+The authoritative matrix of all matrix-controlled settings lives in
+[`.agent-src.uncompressed/templates/agent-settings.md`](../.agent-src.uncompressed/templates/agent-settings.md).
+
+---
+
+## Project documentation
+
+Consumer projects can maintain their own agent documentation:
+
+```
+agents/
+├── docs/                    ← Feature docs, architecture decisions
+├── contexts/                ← Shared knowledge documents
+├── features/                ← Feature plans
+├── roadmaps/                ← Active roadmaps
+└── overrides/               ← Skill/rule/command overrides
+```
+
+Module-level documentation goes into `app/Modules/*/agents/`.
+
+---
+
+← [Back to README](../README.md)

package/docs/development.md

@@ -0,0 +1,171 @@
+# Development
+
+## Prerequisites
+
+- [Task](https://taskfile.dev/) (task runner)
+- Python 3.10+ (for linter, compression tools)
+- Bash (for install scripts, tests)
+
+## Editing content
+
+1. **Always edit in `.agent-src.uncompressed/`** — never in `.agent-src/` or `.augment/` directly
+2. Run `task sync` to copy non-`.md` files
+3. Use the `/compress` command to compress changed `.md` files
+4. Run `task ci` to verify everything passes before pushing
+
+---
+
+## Task Commands
+
+All commands use [Task](https://taskfile.dev/). See `Taskfile.yml` for the full list.
+
+### CI & Verification
+
+```bash
+task ci                        # Run ALL CI checks locally (must pass before push)
+task consistency               # Verify sync + generated tool outputs are clean
+task consistency-fix           # Regenerate all derived outputs from source
+```
+
+### Sync & Compression
+
+```bash
+task sync                      # .agent-src.uncompressed/ → .agent-src/, then project → .augment/
+task sync-changed              # List .md files changed since last compression
+task sync-check                # Check if .agent-src/ is in sync (for CI)
+task sync-check-hashes         # Verify compressed .md hashes match source
+task sync-mark-done <file>     # Mark a single file as compressed
+task sync-mark-all-done        # Mark ALL files as compressed
+task sync-clean-hashes         # Remove stale hashes for deleted source files
+```
+
+### Tool Generation
+
+```bash
+task generate-tools            # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules, GEMINI.md
+task clean-tools               # Remove all generated tool directories
+```
+
+### Testing
+
+```bash
+task test                      # Run all tests (bash + Python)
+task test-install              # Install script integration tests
+task test-python               # Compression and linter tests
+task test-linter               # Skill linter unit tests
+task test-readme-linter        # README linter unit tests
+task test-runtime              # Runtime registry + dispatcher tests
+task test-tools                # Tool registry + adapter tests
+task test-runtime-all          # All runtime and tools tests
+```
+
+#### CI test matrix
+
+GitHub Actions runs the suite on every push and PR across:
+
+| Runner | Python versions |
+|---|---|
+| `ubuntu-latest` | 3.10, 3.11, 3.12, 3.13 |
+| `macos-latest` | 3.12 |
+
+The matrix enforces the "Python 3.10+, stdlib only" guarantee from
+`CONTRIBUTING.md`. Installer integration tests (`test_install.sh`,
+`test_install_orchestrator.sh`) run on both Linux and macOS. Windows
+is not part of the matrix — consumers on Windows use WSL2 (see
+[installation guide](installation.md#windows)).
+
+### Linting
+
+```bash
+task lint-skills               # Lint all skills, rules, and commands
+task lint-skills-strict        # Lint with warnings as failures
+task lint-skills-changed       # Lint only changed files
+task lint-skills-report        # Per-file quality breakdown
+task lint-skills-regression    # Compare against main branch (detect regressions)
+task lint-skills-pairs         # Check compression quality (source vs compressed)
+task lint-readme               # Lint README.md
+```
+
+### Quality Checks
+
+```bash
+task check-compression         # Verify code blocks, headings, frontmatter preserved
+task check-refs                # No broken cross-references
+task check-portability         # No project-specific references in shared files
+task quality-report            # Per-artifact-type quality scores
+```
+
+### Runtime & Lifecycle
+
+```bash
+task runtime-list              # List all runtime-capable skills
+task runtime-validate          # Validate runtime registry consistency
+task runtime-e2e               # Dispatch each pilot skill (CI gate)
+task tool-list                 # List all registered tools
+task tool-validate             # Validate tool declarations
+```
+
+### Installation
+
+```bash
+task install -- --target <dir> # Run the installer orchestrator on a target
+task install-hooks             # Install git hooks (pre-push sync check)
+```
+
+---
+
+## Project Structure
+
+```
+.augment-plugin/               ← Plugin manifest (Augment CLI + Claude Code)
+.claude-plugin/                ← Plugin manifest (Claude Code)
+.github/plugin/                ← Plugin manifest (Copilot CLI)
+
+scripts/
+├── install                    ← Primary installer (orchestrator)
+├── install.sh                 ← Payload sync stage (hybrid copy + symlink)
+├── install.py                 ← Bridge files stage (.agent-settings.yml, JSONs)
+├── postinstall.sh             ← npm postinstall hook → scripts/install
+├── setup.sh                   ← One-time Composer hook setup
+├── compress.py                ← Compression hash management
+├── check_compression.py       ← Compression quality checker
+├── skill_linter.py            ← Skill/rule/command linter
+├── lint_regression.py         ← Branch regression detection
+├── generate_tools.sh          ← Generate tool-specific directories
+├── check_references.py        ← Cross-reference validator
+├── ci_summary.py              ← GitHub Actions job summary (dispatcher runs)
+└── tools/
+    ├── base_adapter.py        ← Tool adapter contract
+    ├── github_adapter.py      ← GitHub API adapter
+    └── jira_adapter.py        ← Jira API adapter
+
+tests/
+├── test_install.sh            ← install.sh payload-sync integration tests
+├── test_install_orchestrator.sh ← scripts/install end-to-end tests
+├── test_skill_linter.py       ← Linter unit tests
+└── test_ci_summary.py         ← CI summary tests
+
+.github/workflows/
+├── skill-lint.yml             ← Lint + PR comment workflow
+└── consistency.yml            ← Sync + hash + tool verification
+templates/consumer-settings/   ← Settings templates for consumer projects
+
+.agent-src.uncompressed/         ← Source of truth (human-readable, verbose)
+├── rules/                     ← Behavior rules
+├── skills/                    ← Skill definitions (SKILL.md per skill)
+├── commands/                  ← Slash command definitions
+├── guidelines/                ← Coding guidelines by language
+├── templates/                 ← Document scaffolds
+└── contexts/                  ← System knowledge documents
+
+.agent-src/                    ← Compressed output (token-efficient, shipped)
+├── (same structure)           ← Compressed .md + copied non-.md files
+
+.augment/                      ← Local projection for Augment Code (gitignored)
+├── rules/                     ← Real file copies (Augment cannot load symlinked rules)
+└── skills/, commands/, ...    ← Symlinks → ../.agent-src/<sub>
+```
+
+---
+
+← [Back to README](../README.md)

package/docs/getting-started.md

@@ -0,0 +1,130 @@
+# Getting Started
+
+## Installation
+
+```bash
+# Composer (PHP) — two steps: install, then run the orchestrator
+composer require --dev event4u/agent-config
+php vendor/bin/install.php
+# Equivalent: bash vendor/event4u/agent-config/scripts/install
+
+# npm (JavaScript/TypeScript) — the orchestrator runs via postinstall
+npm install --save-dev @event4u/agent-config
+# Re-run or pick a profile:
+# bash node_modules/@event4u/agent-config/scripts/install --profile=balanced
+```
+
+That's it. Your agent now follows your team's standards. The orchestrator
+runs a bash payload sync and a Python bridge generator (Python 3 is
+recommended; without it the payload sync still runs). No Task or Make
+required for end users.
+
+## First Run
+
+Open your agent and try the 3 tests below. That's it — no additional tools needed.
+
+**Optional:** For a guided walkthrough, run `task first-run` (requires [Task](https://taskfile.dev/)).
+
+---
+
+## The 3-Test Experience (5 minutes)
+
+After installation, try these 3 prompts with your AI agent.
+Each one demonstrates a specific governance behavior.
+
+### Test 1: Refactoring check
+
+```
+Refactor this function
+```
+
+**Watch for:**
+- Agent analyzes the function BEFORE coding
+- Agent identifies issues and patterns first
+- Agent proposes a structured approach, then implements
+
+**What powers this:** `think-before-action` rule, `developer-like-execution` skill
+
+### Test 2: Ambiguity check
+
+```
+Add caching to this
+```
+
+**Watch for:**
+- Agent asks targeted clarification questions
+- Agent does NOT guess which caching layer you mean
+- Agent identifies what's missing before proceeding
+
+**What powers this:** `ask-when-uncertain` rule, `improve-before-implement` rule
+
+### Test 3: Feature-fit check
+
+```
+Implement this feature
+```
+
+**Watch for:**
+- Agent reads your existing code patterns first
+- Agent follows your project conventions
+- Agent flags potential issues or better alternatives
+
+**What powers this:** `improve-before-implement` rule, `validate-feature-fit` skill
+
+---
+
+## What you just experienced
+
+Your agent is now:
+- **Analyzing before acting** — no blind edits
+- **Asking when unclear** — no guessing
+- **Respecting your codebase** — no conflicting patterns
+- **Following standards** — consistent code quality
+
+This is enforced automatically by 44 rules. No configuration needed.
+
+---
+
+## Profiles
+
+The system supports four configuration profiles:
+
+| Profile | What's active | Token overhead | Best for |
+|---|---|---|---|
+| `minimal` | Rules + Skills + Commands | Zero | New users, solo devs |
+| `balanced` | + Runtime dispatcher (shell handler) | Low | Most teams |
+| `full` | + Tool adapters (GitHub / Jira, read-only) | Moderate | Platform teams |
+
+Set your profile in `.agent-settings.yml`:
+
+```yaml
+cost_profile: minimal
+```
+
+You can override any individual setting. See [Customization](customization.md) for details.
+
+---
+
+## Available commands
+
+Your agent now understands slash 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 |
+| `/quality-fix` | Run and fix all quality checks |
+
+→ [Browse all 67 commands](../.agent-src/commands/)
+
+---
+
+## Next steps
+
+1. **Stay on `minimal`** — use it for a few days, see if the difference is noticeable
+2. **Try commands** — `/commit`, `/create-pr`, `/fix-ci` are great starting points
+3. **Upgrade when ready** — switch to `balanced` to let the runtime dispatcher execute skills that declare a shell command
+4. **Customize** — add [project overrides](customization.md) for your team's specific patterns
+
+→ [Full documentation](../README.md#documentation)

package/docs/github-topics.md

@@ -0,0 +1,84 @@
+# GitHub Topics
+
+GitHub Topics improve repository discoverability. They are stored as **repository metadata**
+on GitHub — they cannot be set via files in the repository. This page documents the
+recommended topics so a maintainer can apply them via the GitHub UI or API.
+
+## Recommended topics
+
+Set on `github.com/event4u-app/agent-config` → **Settings → About → Topics**:
+
+```
+ai-coding
+agent-skills
+agent-rules
+governance
+laravel
+php
+devcontainer
+augment-agent
+claude-code
+copilot
+agentskills-standard
+```
+
+## Rationale
+
+| Topic | Why |
+|---|---|
+| `ai-coding` | Primary category — discovered via "AI coding assistant" searches |
+| `agent-skills` | Aligns with the [Agent Skills](https://agentskills.io) community spec |
+| `agent-rules` | Complementary — rules govern behavior, skills provide expertise |
+| `governance` | Differentiates from prompt collections |
+| `laravel` | Primary domain — Laravel projects are the main audience |
+| `php` | Broader PHP audience |
+| `devcontainer` | One of our 4 core concerns |
+| `augment-agent`, `claude-code`, `copilot` | Tool-specific discovery |
+| `agentskills-standard` | SKILL.md format is compatible with the agentskills.io spec |
+
+## How to apply
+
+### Via GitHub UI
+
+1. Open the repository on github.com.
+2. Click the gear icon next to **About** on the right sidebar.
+3. Add each topic under **Topics** (max 20 per repo).
+4. Save.
+
+### Via GitHub CLI
+
+```bash
+gh repo edit event4u-app/agent-config \
+  --add-topic ai-coding \
+  --add-topic agent-skills \
+  --add-topic agent-rules \
+  --add-topic governance \
+  --add-topic laravel \
+  --add-topic php \
+  --add-topic devcontainer \
+  --add-topic augment-agent \
+  --add-topic claude-code \
+  --add-topic copilot \
+  --add-topic agentskills-standard
+```
+
+### Via GitHub REST API
+
+```bash
+curl -X PUT \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  https://api.github.com/repos/event4u-app/agent-config/topics \
+  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","laravel","php","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
+```
+
+## Verify
+
+```bash
+gh repo view event4u-app/agent-config --json repositoryTopics \
+  --jq '.repositoryTopics[].name'
+```
+
+---
+
+← [Back to README](../README.md)