@event4u/agent-config 1.9.1

package/.agent-src/templates/scripts/pr_risk_review.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+PR risk classifier.
+
+Reads a list of changed files between two git refs, matches each path against
+glob patterns defined in a YAML config, and emits a Markdown report plus a
+single-word risk level (low / medium / high) for downstream CI steps.
+
+The classifier is intentionally heuristic — it flags paths that historically
+correlate with higher blast radius (migrations, auth code, lockfiles, public
+endpoints). It is a conversation starter for reviewers, not a merge gate.
+
+Config file format — see `pr-risk-config.example.yml` alongside this script.
+
+Usage:
+    python3 pr_risk_review.py \\
+        --base <sha> --head <sha> \\
+        --config .github/pr-risk-config.yml \\
+        --output risk-report.md \\
+        --level-file risk-level.txt
+
+Exit codes: 0 = success, 2 = invalid arguments, 3 = git/config error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:
+    print("error: pyyaml not installed (pip install pyyaml)", file=sys.stderr)
+    sys.exit(3)
+
+LEVELS = ("high", "medium", "low")
+DEFAULT_CONFIG: dict[str, Any] = {
+    "patterns": {
+        "high": [
+            "**/migrations/**", "**/migration/**", "**/*.sql",
+            "**/auth/**", "**/security/**", "**/policies/**",
+            "**/.env*", "**/secrets/**",
+            "composer.lock", "package-lock.json", "pnpm-lock.yaml",
+            "yarn.lock", "poetry.lock", "Gemfile.lock", "go.sum",
+            "**/Dockerfile*", "**/docker-compose*.y*ml",
+            ".github/workflows/**",
+        ],
+        "medium": [
+            "**/queue/**", "**/queues/**", "**/jobs/**", "**/listeners/**",
+            "**/routes/**", "**/controllers/**", "**/api/**",
+            "**/schema/**", "**/models/**", "**/entities/**",
+            "composer.json", "package.json", "pyproject.toml", "Gemfile",
+        ],
+    },
+    "ignore": [
+        "**/*.md", "**/CHANGELOG*", "**/docs/**",
+        "**/*.lock.hcl",
+    ],
+}
+
+
+@dataclass
+class Match:
+    level: str
+    pattern: str
+    paths: list[str] = field(default_factory=list)
+
+
+@lru_cache(maxsize=512)
+def _compile(pattern: str) -> re.Pattern[str]:
+    """Translate a gitignore-ish glob to a regex.
+
+    - ``**/`` matches zero or more leading path segments.
+    - ``/**`` matches zero or more trailing path segments.
+    - ``**`` matches any characters (including ``/``).
+    - ``*`` matches any characters except ``/`` (single segment).
+    - ``?`` matches a single non-slash character.
+    """
+    out: list[str] = []
+    i, n = 0, len(pattern)
+    while i < n:
+        c = pattern[i]
+        if c == "*":
+            if i + 1 < n and pattern[i + 1] == "*":
+                if i + 2 < n and pattern[i + 2] == "/":
+                    out.append("(?:.*/)?")
+                    i += 3
+                    continue
+                if i > 0 and pattern[i - 1] == "/":
+                    out[-1] = "(?:/.*)?"  # replace the trailing '/'
+                    i += 2
+                    continue
+                out.append(".*")
+                i += 2
+                continue
+            out.append("[^/]*")
+        elif c == "?":
+            out.append("[^/]")
+        elif c in r".^$+{}()[]|\\":
+            out.append(re.escape(c))
+        else:
+            out.append(c)
+        i += 1
+    return re.compile("^" + "".join(out) + "$")
+
+
+def _match(path: str, pattern: str) -> bool:
+    return bool(_compile(pattern).match(path))
+
+
+def load_config(path: Path | None) -> dict[str, Any]:
+    if path is None or not path.exists():
+        return DEFAULT_CONFIG
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        print(f"error: config parse failed: {exc}", file=sys.stderr)
+        sys.exit(3)
+    return {**DEFAULT_CONFIG, **data}
+
+
+def changed_files(base: str, head: str) -> list[str]:
+    try:
+        out = subprocess.run(
+            ["git", "diff", "--name-only", f"{base}...{head}"],
+            check=True, capture_output=True, text=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        print(f"error: git diff failed: {exc.stderr}", file=sys.stderr)
+        sys.exit(3)
+    return [line for line in out.stdout.splitlines() if line.strip()]
+
+
+def classify(files: list[str], config: dict[str, Any]) -> tuple[str, list[Match]]:
+    ignore = config.get("ignore", []) or []
+    files = [f for f in files if not any(_match(f, p) for p in ignore)]
+    patterns = config.get("patterns", {}) or {}
+
+    hits: dict[tuple[str, str], Match] = {}
+    for level in ("high", "medium"):
+        for pattern in patterns.get(level, []) or []:
+            matched = [f for f in files if _match(f, pattern)]
+            if matched:
+                hits[(level, pattern)] = Match(level, pattern, matched)
+
+    level = "high" if any(k[0] == "high" for k in hits) else (
+        "medium" if any(k[0] == "medium" for k in hits) else "low"
+    )
+    return level, list(hits.values())
+
+
+def render(level: str, hits: list[Match], total: int) -> str:
+    emoji = {"high": "🔴", "medium": "🟡", "low": "🟢"}[level]
+    lines = [
+        f"## {emoji} PR Risk: **{level}**",
+        "",
+        f"_{total} changed file(s), {len(hits)} risk signal(s)._",
+        "",
+    ]
+    if not hits:
+        lines += [
+            "No high- or medium-risk patterns matched. Reviewers: still ",
+            "inspect the diff — the classifier only flags known hotspots.",
+        ]
+        return "\n".join(lines) + "\n"
+
+    for lvl in ("high", "medium"):
+        bucket = [h for h in hits if h.level == lvl]
+        if not bucket:
+            continue
+        lines.append(f"### {emoji if lvl == level else ('🟡' if lvl == 'medium' else '🟢')} {lvl.capitalize()}")
+        for m in bucket:
+            lines.append(f"- `{m.pattern}` — {len(m.paths)} file(s)")
+            lines += [f"  - `{p}`" for p in m.paths[:5]]
+            if len(m.paths) > 5:
+                lines.append(f"  - … and {len(m.paths) - 5} more")
+        lines.append("")
+
+    lines += [
+        "---",
+        "_Classifier is heuristic. Merge is not blocked by this check._",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base", required=True)
+    parser.add_argument("--head", required=True)
+    parser.add_argument("--config", type=Path, default=None)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--level-file", type=Path, required=True)
+    args = parser.parse_args()
+
+    config = load_config(args.config)
+    files = changed_files(args.base, args.head)
+    level, hits = classify(files, config)
+
+    args.output.write_text(render(level, hits, len(files)), encoding="utf-8")
+    args.level_file.write_text(level, encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agent-src/templates/skill.md

@@ -0,0 +1,136 @@
+# Skill Template
+
+> Template for creating new skills in `.augment/skills/{skill-name}/SKILL.md`.
+
+## Instructions
+
+1. Create directory: `.augment/skills/{skill-name}/`
+2. Copy the template below into `SKILL.md`
+3. Replace all `{placeholders}` with actual content
+4. Remove sections that don't apply
+5. Remove all `<!-- comments -->` when done
+
+## Template
+
+````markdown
+---
+name: {skill-name}
+description: "Use when {trigger situation — what the user says or does}. {What the skill does in 1 sentence}."
+status: active
+---
+
+<!-- STATUS VALUES (delete this comment when done):
+  - active: default, skill is in use
+  - deprecated: better alternative exists (add replaced_by if applicable)
+  - superseded: fully replaced by another skill (add replaced_by)
+  Example: status: deprecated
+           replaced_by: other-skill-name
+-->
+
+<!-- EXECUTION METADATA (optional — delete this comment when done):
+  Add if the skill supports controlled execution beyond instructional use.
+  Omit entirely for manual/instructional-only skills.
+
+  execution:
+    type: manual | assisted | automated
+    handler: none | shell | php | node | internal
+    timeout_seconds: 30
+    safety_mode: strict
+    allowed_tools: []
+
+  See guidelines/agent-infra/runtime-layer.md for details.
+-->
+
+<!-- DESCRIPTION RULES (delete this comment when done):
+  - Start with "Use when..." — this is a TRIGGER, not a summary
+  - Include 2-3 phrases users actually say: "create a DTO", "add column", "fix tests"
+  - For explicit-only skills: "ONLY when user explicitly requests: [X]. NOT for [Y]."
+  - Keep it under 200 chars — it's loaded into the system prompt on every conversation
+  - Write in third person — the skill description is injected as context, not spoken by the agent
+-->
+
+# {skill-name}
+
+## When to use
+
+Use this skill when:
+- {Scenario 1}
+- {Scenario 2}
+- {Scenario 3}
+
+Do NOT use when:
+- {Wrong scenario — suggest alternative skill}
+- {Another wrong scenario}
+
+## Before writing code
+
+<!-- Optional — checklist to run before starting work. Delete if not applicable. -->
+
+1. **Detect {thing}** — check {file} for {what to look for}.
+2. **Check {convention}** — read {reference}.
+3. **Read project docs** — `./agents/`, module-specific docs if applicable.
+
+## Procedure: {skill-name}
+
+<!-- REQUIRED — The core workflow. Use "Procedure" or "Procedure: {name}" as heading.
+  - Numbered steps with concrete commands or actions
+  - Each step independently verifiable
+  - End with a validation/verification step
+  - For coding skills: include code examples in steps
+  - For process skills: workflow phases with decision points
+  - For tool skills: commands with expected output -->
+
+### Step 0: Inspect
+
+1. {What to check before starting — existing code, conventions, project docs}
+
+### Step 1: {action}
+
+1. {Concrete step}
+2. {Concrete step}
+
+### Step 2: Validate
+
+1. {Concrete check — command output, test result, or assertion}
+2. {Second check}
+
+## Output format
+
+<!-- REQUIRED — What the skill produces. Use numbered list with 2-4 items.
+  Describe the deliverables, not the process. -->
+
+1. {Primary deliverable — file, config, report}
+2. {Secondary deliverable or verification result}
+
+## Gotcha
+
+<!-- REQUIRED — The highest-value section in any skill.
+  Document failure patterns the model actually hits — not theoretical advice.
+  Format: "The model tends to X — do Y instead" or "Don't assume X because Y".
+  Grow this organically: add entries when real failures happen. Seed with 2-3 known issues. -->
+
+- {The model tends to do X when Y — instead, do Z.}
+- {Don't assume X — check Y first because Z.}
+- {Edge case: when A happens, do B instead of C.}
+
+## Do NOT
+
+- Do NOT {anti-pattern 1}.
+- Do NOT {anti-pattern 2}.
+- Do NOT {anti-pattern 3}.
+````
+
+## Quality Checklist (5 Skill Killers)
+
+Before considering a skill complete, verify it passes all 5 checks:
+
+- [ ] **K1: Description is a trigger** — starts with "Use when...", includes phrases users actually say, is specific enough for skill discovery
+- [ ] **K2: Not over-defined** — guides rather than railroads; tight for fragile ops, loose for creative tasks; <15 numbered steps
+- [ ] **K3: No obvious content** — doesn't teach the model what it already knows; only project-specific conventions and non-obvious patterns
+- [ ] **K4: Has Gotcha section** — documents real failure patterns, not theoretical advice; seeded with 2-3 entries
+- [ ] **K5: Has Output format** — numbered list with 2-4 deliverables describing what the skill produces
+- [ ] **K6: Under 500 lines** — if larger, extract reference tables or templates into separate files in the skill folder
+- [ ] **English only** — all content in English
+- [ ] **No duplication** — doesn't repeat rules or guidelines that are already enforced elsewhere
+- [ ] **No "Related skills" section** — the agent discovers skills via `<available_skills>` descriptions; cross-links waste tokens and create maintenance burden
+

package/.augment-plugin/marketplace.json

@@ -0,0 +1,32 @@
+{
+  "name": "event4u-agent-config",
+  "description": "Governed agent system — skills, rules, commands, and guidelines for AI-assisted development.",
+  "version": "1.0.0",
+  "owner": {
+    "name": "event4u",
+    "email": "dev@event4u.app"
+  },
+  "metadata": {
+    "description": "A policy-driven execution system that enforces quality, consistency, and developer-like behavior for AI agents.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "agent-config",
+      "description": "Full governed agent system — rules, skills, commands, guidelines, and runtime tooling.",
+      "version": "1.0.0",
+      "source": ".",
+      "category": "governance",
+      "tags": [
+        "governance",
+        "skills",
+        "rules",
+        "commands",
+        "guidelines",
+        "laravel",
+        "php",
+        "quality"
+      ]
+    }
+  ]
+}

package/.augment-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "agent-config",
+  "description": "A governed skill framework for AI agents — runtime execution, tooling, observability, feedback, and lifecycle management with policy-driven quality enforcement.",
+  "version": "1.0.0",
+  "author": {
+    "name": "event4u",
+    "email": "dev@event4u.app"
+  },
+  "repository": "https://github.com/event4u-app/agent-config",
+  "keywords": [
+    "governance",
+    "skills",
+    "rules",
+    "commands",
+    "guidelines",
+    "laravel",
+    "php",
+    "quality",
+    "agent-config"
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,119 @@
+{
+  "name": "event4u-agent-config",
+  "owner": {
+    "name": "event4u",
+    "email": "dev@event4u.app"
+  },
+  "metadata": {
+    "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
+    "version": "1.9.1"
+  },
+  "plugins": [
+    {
+      "name": "agent-config",
+      "description": "Full skill catalog \u2014 writing, reviewing, managing, and analyzing agent content, plus stack-specific skills for Laravel, PHP, Docker, AWS, Playwright, and more.",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./.claude/skills/adversarial-review",
+        "./.claude/skills/agent-docs-writing",
+        "./.claude/skills/analysis-autonomous-mode",
+        "./.claude/skills/analysis-skill-router",
+        "./.claude/skills/api-design",
+        "./.claude/skills/api-endpoint",
+        "./.claude/skills/api-testing",
+        "./.claude/skills/artisan-commands",
+        "./.claude/skills/aws-infrastructure",
+        "./.claude/skills/blade-ui",
+        "./.claude/skills/bug-analyzer",
+        "./.claude/skills/code-refactoring",
+        "./.claude/skills/code-review",
+        "./.claude/skills/command-routing",
+        "./.claude/skills/composer-packages",
+        "./.claude/skills/context-document",
+        "./.claude/skills/conventional-commits-writing",
+        "./.claude/skills/copilot-agents-optimization",
+        "./.claude/skills/copilot-config",
+        "./.claude/skills/dashboard-design",
+        "./.claude/skills/database",
+        "./.claude/skills/dependency-upgrade",
+        "./.claude/skills/design-review",
+        "./.claude/skills/devcontainer",
+        "./.claude/skills/developer-like-execution",
+        "./.claude/skills/docker",
+        "./.claude/skills/dto-creator",
+        "./.claude/skills/eloquent",
+        "./.claude/skills/fe-design",
+        "./.claude/skills/feature-planning",
+        "./.claude/skills/file-editor",
+        "./.claude/skills/flux",
+        "./.claude/skills/git-workflow",
+        "./.claude/skills/github-ci",
+        "./.claude/skills/grafana",
+        "./.claude/skills/jira-integration",
+        "./.claude/skills/jobs-events",
+        "./.claude/skills/laravel",
+        "./.claude/skills/laravel-horizon",
+        "./.claude/skills/laravel-mail",
+        "./.claude/skills/laravel-middleware",
+        "./.claude/skills/laravel-notifications",
+        "./.claude/skills/laravel-pennant",
+        "./.claude/skills/laravel-pulse",
+        "./.claude/skills/laravel-reverb",
+        "./.claude/skills/laravel-scheduling",
+        "./.claude/skills/laravel-validation",
+        "./.claude/skills/learning-to-rule-or-skill",
+        "./.claude/skills/livewire",
+        "./.claude/skills/logging-monitoring",
+        "./.claude/skills/mcp",
+        "./.claude/skills/merge-conflicts",
+        "./.claude/skills/migration-creator",
+        "./.claude/skills/module-management",
+        "./.claude/skills/multi-tenancy",
+        "./.claude/skills/openapi",
+        "./.claude/skills/override-management",
+        "./.claude/skills/performance",
+        "./.claude/skills/performance-analysis",
+        "./.claude/skills/pest-testing",
+        "./.claude/skills/php-coder",
+        "./.claude/skills/php-debugging",
+        "./.claude/skills/php-service",
+        "./.claude/skills/playwright-testing",
+        "./.claude/skills/project-analysis-core",
+        "./.claude/skills/project-analysis-hypothesis-driven",
+        "./.claude/skills/project-analysis-laravel",
+        "./.claude/skills/project-analysis-nextjs",
+        "./.claude/skills/project-analysis-node-express",
+        "./.claude/skills/project-analysis-react",
+        "./.claude/skills/project-analysis-symfony",
+        "./.claude/skills/project-analysis-zend-laminas",
+        "./.claude/skills/project-analyzer",
+        "./.claude/skills/project-docs",
+        "./.claude/skills/quality-tools",
+        "./.claude/skills/readme-reviewer",
+        "./.claude/skills/readme-writing",
+        "./.claude/skills/readme-writing-package",
+        "./.claude/skills/roadmap-management",
+        "./.claude/skills/rtk-output-filtering",
+        "./.claude/skills/security",
+        "./.claude/skills/security-audit",
+        "./.claude/skills/sentry-integration",
+        "./.claude/skills/sequential-thinking",
+        "./.claude/skills/skill-improvement-pipeline",
+        "./.claude/skills/skill-management",
+        "./.claude/skills/skill-reviewer",
+        "./.claude/skills/skill-writing",
+        "./.claude/skills/sql-writing",
+        "./.claude/skills/technical-specification",
+        "./.claude/skills/terraform",
+        "./.claude/skills/terragrunt",
+        "./.claude/skills/test-performance",
+        "./.claude/skills/traefik",
+        "./.claude/skills/universal-project-analysis",
+        "./.claude/skills/upstream-contribute",
+        "./.claude/skills/validate-feature-fit",
+        "./.claude/skills/websocket"
+      ]
+    }
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,121 @@
+# event4u/agent-config
+
+**Shared agent configuration** — skills, rules, commands, guidelines, and templates
+for AI coding tools (Augment Code, Claude Code, Cursor, Cline, Windsurf, Gemini CLI,
+GitHub Copilot).
+
+This file is the AGENTS.md **of the package itself**. It gives an agent that is
+working **on this repository** (adding skills, fixing the installer, improving
+the linter) the context it needs. Consumer projects get their own AGENTS.md
+generated from [`.augment/templates/AGENTS.md`](.agent-src/templates/AGENTS.md)
+when they install the package.
+
+## What this repo is
+
+- A distribution package, not an application.
+- `type: library` in `composer.json`; no `app/` directory, no Laravel runtime.
+- Published to Composer and npm as `event4u/agent-config` / `@event4u/agent-config`.
+- Installed into consumer projects via `scripts/install.sh` (Bash) and
+  `scripts/install.py` (Python bridge).
+
+## Source of truth
+
+| Directory | Purpose | Editable? |
+|---|---|---|
+| `.agent-src.uncompressed/` | Authoring layer — full verbose content | ✅ Yes — edit here |
+| `.agent-src/` | Compressed output — shipped in the package, consumed by agents | ❌ No — regenerated |
+| `.augment/` | Local projection of `.agent-src/` for Augment Code (gitignored) | ❌ No — regenerated |
+| `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` | Tool-specific projections | ❌ No — regenerated |
+| `agents/` | Package's own roadmaps, contexts, sessions | ✅ Yes |
+
+**Never edit `.agent-src/` or `.augment/` directly.** Edit `.agent-src.uncompressed/`
+and run `task sync` (or `task ci`) to compress + regenerate the tool directories.
+
+## Tech stack of this package
+
+- **Bash** — install scripts, compression driver
+- **Python 3.10+** — linters (`scripts/skill_linter.py`, `scripts/check_portability.py`,
+  `scripts/check_references.py`, `scripts/readme_linter.py`), compression tooling,
+  test suite (pytest)
+- **Markdown** — all content (skills, rules, commands, guidelines, templates)
+- **Taskfile** — developer entrypoints (`task ci`, `task sync`, `task test`)
+- **GitHub Actions** — CI workflow under `.github/workflows/`
+
+No PHP, no Laravel, no JavaScript runtime dependencies. The `composer.json` /
+`package.json` are thin distribution manifests.
+
+## Working on this repo
+
+```bash
+task sync          # .agent-src.uncompressed/ → .agent-src/, then project → .augment/
+task generate-tools # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
+task test          # pytest tests/ + tests/test_install.sh
+task lint-skills   # python3 scripts/skill_linter.py --all
+task ci            # Full pipeline — must be green before PR
+```
+
+All checks must pass before a PR: sync-check, consistency, check-compression,
+check-refs, check-portability, lint-skills, test, lint-readme.
+
+## Key rules for agents editing this repo
+
+| Rule | File |
+|---|---|
+| `.agent-src/` must stay project-agnostic — no project names, domains, stacks | [`augment-portability`](.agent-src/rules/augment-portability.md) |
+| Root AGENTS.md + copilot-instructions.md must stay project-agnostic too | [`augment-portability`](.agent-src/rules/augment-portability.md) |
+| Edit `.agent-src.uncompressed/`, never `.agent-src/` or `.augment/` | [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md) |
+| Skills must declare frontmatter, be self-contained, pass the linter | [`skill-quality`](.agent-src/rules/skill-quality.md) |
+| Size budgets for skills, rules, commands | [`size-enforcement`](.agent-src/rules/size-enforcement.md) |
+| Keep `.agent-src/` / `agents/` cross-refs in sync on add/rename/delete | [`docs-sync`](.agent-src/rules/docs-sync.md) |
+| Creating a new skill/rule/command/guideline runs Understand → Research → Draft | [`artifact-drafting-protocol`](.agent-src/rules/artifact-drafting-protocol.md) |
+
+## Repository layout
+
+```
+.agent-src.uncompressed/      ← edit here
+  skills/       (124 skills)
+  rules/        (44 rules)
+  commands/     (67 commands)
+  guidelines/   (46 guidelines)
+  personas/     (7 personas)
+  templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
+  contexts/
+
+.agent-src/                 ← compressed output shipped in the package
+.augment/                   ← local projection for Augment Code (gitignored)
+scripts/                    ← install.sh, install.py, compress.py, linters
+tests/                      ← pytest (324 tests) + test_install.sh
+agents/                     ← this package's own roadmaps / sessions / contexts
+.github/workflows/          ← CI
+```
+
+## Multi-agent tool support
+
+`task generate-tools` builds:
+
+| Tool | Output | Strategy |
+|---|---|---|
+| Augment Code | `.augment/` | Native (source) |
+| Claude Code | `.claude/rules/`, `.claude/skills/` | Symlinks + Agent Skills standard |
+| Cursor | `.cursor/rules/` | Symlinks |
+| Cline | `.clinerules/` | Symlinks |
+| Windsurf | `.windsurfrules` | Concatenated file |
+| Gemini CLI | `GEMINI.md` | Symlink → AGENTS.md |
+
+Skills follow the [Agent Skills open standard](https://agentskills.io). Commands
+are converted to Claude Code Skills with `disable-model-invocation: true`.
+
+## Contributing
+
+1. Edit inside `.agent-src.uncompressed/` or `scripts/` or `tests/` — never in
+   `.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, etc.
+2. Run `task ci` locally. It must exit 0.
+3. Commit in logical chunks with Conventional Commits.
+4. Open a PR against `main`.
+
+See [`README.md`](README.md) for the user-facing story, and
+[`docs/architecture.md`](docs/architecture.md) for the package architecture.
+
+## License
+
+[MIT](LICENSE).