@event4u/agent-config 1.9.1

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

@@ -0,0 +1,24 @@
+# Override: Skill — {skill-name}
+
+> Override for `.augment/skills/{skill-name}/SKILL.md`
+
+---
+**Mode:** `extend` | `replace`
+**Original:** `.augment/skills/{skill-name}/SKILL.md`
+---
+
+<!-- MODE EXPLANATION:
+  - extend:  The original skill is loaded FIRST, then this file adds to or modifies specific sections.
+             Use this to add project-specific behavior, extra steps, or constraints.
+  - replace: The original skill is IGNORED entirely. This file is the sole source of truth.
+             Use this when the original skill does not fit the project at all.
+-->
+
+## Additional Behavior
+
+<!-- For mode: extend — describe what to add or change. Reference original sections by heading. -->
+
+## Replaced Sections
+
+<!-- For mode: replace — write the complete skill definition from scratch. -->
+

package/.agent-src/templates/overrides/template.md

@@ -0,0 +1,21 @@
+# Override: Template — {template-name}
+
+> Override for `.augment/templates/{template-name}.md`
+
+---
+**Mode:** `extend` | `replace`
+**Original:** `.augment/templates/{template-name}.md`
+---
+
+<!-- MODE EXPLANATION:
+  - extend:  The original template is loaded FIRST, then this file adds or modifies sections/fields.
+             Use this to add project-specific fields, change default values, or add extra rules.
+  - replace: The original template is IGNORED entirely. This file defines the full template.
+             Use this when the project needs a fundamentally different document structure.
+-->
+
+## Modified Sections
+
+<!-- For mode: extend — only list what changes. Reference original sections by heading. -->
+<!-- For mode: replace — write the complete template from scratch. -->
+

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

@@ -0,0 +1,99 @@
+# Persona Template
+
+> Template for creating a new persona in
+> `.agent-src.uncompressed/personas/{persona-id}.md`. Personas declare
+> a *voice* — focus, mindset, unique questions, output expectations.
+> Skills cite personas in a `personas:` frontmatter key. Users invoke
+> them via `--personas=<id>`.
+
+## Instructions
+
+1. Create the file: `.agent-src.uncompressed/personas/{persona-id}.md`.
+2. Copy the template below.
+3. Replace all `{placeholders}` with real content.
+4. Pass the Unique-Questions heuristic — ≥ 3 questions that no other
+   persona asks verbatim. If you cannot write three unique questions,
+   the persona is redundant; drop it.
+5. Stay within the size budget: **Core ≤ 120 lines, Specialist ≤ 80 lines**.
+6. Run `task sync` and `task ci` before commit.
+
+## Template
+
+````markdown
+---
+id: {persona-id}
+role: {Human-readable role name}
+description: "One line — the voice this persona brings to a review."
+tier: core | specialist
+mode: developer | reviewer | tester | product-owner | incident | planner
+version: "1.0"
+source: package
+---
+
+<!-- FRONTMATTER NOTES (delete this comment when done):
+  - id              required — lowercase, hyphenated, matches filename
+  - role            required — short human-readable role name
+  - description     required — one sentence, ≤ 160 chars
+  - tier            required — "core" (always-loaded cast) or "specialist" (opt-in)
+  - mode            optional — advisory link to a role-contracts workflow mode
+  - version         required — semantic version; bump on breaking changes
+  - source          required — "package" for personas shipped in .agent-src/
+-->
+
+# {Role name}
+
+## Focus
+
+{One short paragraph — what this persona cares about above all else.
+Name the lens, not the job title. Keep it tight.}
+
+## Mindset
+
+- {Bullet — a default assumption this persona makes.}
+- {Bullet — a skepticism it carries into every review.}
+- {Bullet — the trade-off it will defend when others bend.}
+
+## Unique Questions
+
+<!-- ≥ 3 questions nobody else asks. These are the reason the persona
+     exists. If another persona asks one of these, rephrase or drop. -->
+
+- {Question 1 — the one nobody else in the cast will ask.}
+- {Question 2 — a concrete scenario, not a generality.}
+- {Question 3 — rooted in this persona's unique lens.}
+
+## Output Expectations
+
+{How this persona phrases its findings. Blunt? Structured? With
+numbered options? With a recommendation or a verdict? Keep it to
+one short paragraph.}
+
+## Anti-Patterns
+
+- Do NOT {pattern this persona must avoid — e.g. "play code reviewer"}.
+- Do NOT {pattern — e.g. "soften questions for politeness"}.
+- Do NOT {pattern — e.g. "repeat what {other-persona} already said"}.
+
+## Composes well with
+
+<!-- Optional — advisory list of personas this one pairs well with.
+     Not enforcing; skills may still combine any personas they want. -->
+
+- `{other-persona-id}` — {why they complement each other}
+````
+
+## Quality checklist
+
+Before considering a persona complete:
+
+- [ ] **Unique Questions heuristic** — ≥ 3 questions that no other
+  persona asks verbatim. The linter enforces this.
+- [ ] **Size budget** — Core ≤ 120 lines, Specialist ≤ 80 lines.
+- [ ] **Portability** — no project names, domains, stacks, teams.
+- [ ] **English only** — all content in English.
+- [ ] **One sentence description** — ≤ 160 chars, starts with a voice
+  noun ("The voice of ...", "A … lens").
+- [ ] **Anti-Patterns present** — spells out what this persona must
+  refuse to do.
+- [ ] **No "related skills" dump** — personas are referenced *by*
+  skills, not the other way around.

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

@@ -0,0 +1,109 @@
+# Roadmap Template
+
+Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module}/agents/roadmaps/`.
+
+---
+
+## Rules for Roadmaps
+
+1. **Be precise and concise.** Aim for 500–1000 lines max. If larger, split into multiple files.
+2. **Use checkboxes** (`- [ ]`) for every actionable step. Mark `[x]` when completed.
+3. **State the goal first.** One sentence at the top — what is the outcome?
+4. **List prerequisites** — what must exist or be running before starting.
+5. **Reference existing code** — point to files, classes, or modules.
+6. **Define acceptance criteria** — how do we know the task is done?
+7. **Include quality gates** — which commands must pass.
+8. **Language:** All roadmap files must be written in **English**.
+9. **Improve on read:** When processing a roadmap, check if it follows this template and suggest
+   improvements if it doesn't.
+10. **Keep docs up to date:** If changes affect documented behavior, update the relevant agent docs.
+11. **One task per file.** Don't combine unrelated work.
+12. **Lifecycle:** Every roadmap ends in exactly one folder:
+    - `agents/roadmaps/` — active (in progress or planned)
+    - `agents/roadmaps/archive/` — work happened (fully or partially); no further work planned
+    - `agents/roadmaps/skipped/` — decision against pursuit; typically 0 items `[x]` (superseded, scope rejected)
+
+    See the `roadmap-management` skill for the exact trigger matrix and user-confirmation flow.
+
+13. **No tags, releases, or version numbers.** Roadmaps describe work, not shipping.
+    Never assign version suffixes to phases (`Phase 1 — v1.8.0`), never write
+    "Target release: X.Y.Z", never plan git tags. Release and tag decisions
+    belong to the user and are taken outside the roadmap.
+
+---
+
+## Quality Gates (always apply)
+
+Every roadmap must pass these before it is considered done:
+
+Run the project's quality pipeline and test suite. Common commands:
+
+```bash
+# PHP projects (inside Docker container if applicable)
+vendor/bin/phpstan analyse           # Static analysis
+vendor/bin/rector process            # Auto-fix refactoring
+vendor/bin/ecs check --fix           # Auto-fix code style
+php artisan test                     # Tests (or: vendor/bin/phpunit)
+
+# Non-Laravel projects — check Makefile/Taskfile for quality commands
+```
+
+Check `AGENTS.md` or `Makefile` / `Taskfile.yml` for the exact commands.
+
+---
+
+## Template
+
+Copy the structure below into a new file:
+
+```markdown
+# Roadmap: {Short descriptive title}
+
+> {One sentence: What is the expected outcome?}
+
+## Prerequisites
+
+- [ ] Read `AGENTS.md` and relevant module docs
+- [ ] {specific prerequisites}
+
+## Context
+
+{Why this roadmap exists. Which module/domain. Links to Jira tickets and feature plans.}
+
+- **Feature:** {path to feature plan or "none"}
+- **Jira:** {ticket links or "none"}
+
+## Phase 1: {Phase name}
+
+- [ ] **Step 1:** {Clear, actionable instruction}
+- [ ] **Step 2:** {Next step — reference files/classes}
+- [ ] ...
+
+## Phase 2: {Phase name}
+
+- [ ] **Step 1:** {description}
+- [ ] ...
+
+## Acceptance Criteria
+
+- [ ] {Observable, testable criterion}
+- [ ] All quality gates pass (PHPStan, Rector, tests)
+
+## Notes
+
+{Optional: edge cases, decisions, links to related docs.}
+```
+
+---
+
+## Tips
+
+- **Don't describe architecture** the agent can read from `AGENTS.md` — just reference it.
+- **Don't repeat coding standards** — they live in `.github/copilot-instructions.md`.
+- **Do reference specific files:** "See `app/Modules/Import/App/Services/ImportService.php`"
+  is better than "look at the import service."
+- **Do define boundaries:** State what the agent should NOT touch or change.
+- **Do include example inputs/outputs** for non-obvious behavior.
+- **Do split large tasks** — an agent works better with a focused 500-line file than a sprawling 2000-line one.
+- **One task per file.** Don't combine unrelated work.
+

package/.agent-src/templates/scripts/README.md

@@ -0,0 +1,195 @@
+# PR Risk Review — installation
+
+Heuristic PR risk classifier **and** review routing. Posts two sticky
+comments on every non-draft PR:
+
+- **PR Risk** — `low / medium / high` label plus matched hotspots;
+  applies a `risk:<level>` label.
+- **Review Routing** — owner-mapped reviewer roles from
+  `ownership-map.yml` and any matched entries from
+  `historical-bug-patterns.yml`.
+
+Both are **informational** — conversation starters for reviewers, not
+merge gates. Add a separate required check if you want a hard stop on
+high-risk PRs.
+
+## What gets installed
+
+| File in package | Copy to | Purpose |
+|---|---|---|
+| `templates/github-workflows/pr-risk-review.yml` | `.github/workflows/pr-risk-review.yml` | GitHub Actions workflow |
+| `templates/scripts/pr_risk_review.py` | `scripts/pr_risk_review.py` | Risk classifier (Python 3.10+, PyYAML) |
+| `templates/scripts/pr_review_routing.py` | `scripts/pr_review_routing.py` | Routing classifier |
+| `templates/scripts/pr-risk-config.example.yml` | `.github/pr-risk-config.yml` | Risk patterns (optional) |
+| `templates/scripts/ownership-map.example.yml` | `.github/ownership-map.yml` | Ownership entries (optional) |
+| `templates/scripts/historical-bug-patterns.example.yml` | `.github/historical-bug-patterns.yml` | Registered failure modes (optional) |
+
+## Install
+
+```bash
+# from the consumer repo root
+cp .augment/templates/github-workflows/pr-risk-review.yml    .github/workflows/
+cp .augment/templates/scripts/pr_risk_review.py              scripts/
+cp .augment/templates/scripts/pr_review_routing.py           scripts/
+cp .augment/templates/scripts/pr-risk-config.example.yml     .github/pr-risk-config.yml
+cp .augment/templates/scripts/ownership-map.example.yml      .github/ownership-map.yml
+cp .augment/templates/scripts/historical-bug-patterns.example.yml .github/historical-bug-patterns.yml
+```
+
+The routing step in the workflow is **conditional** — it only runs if
+`scripts/pr_review_routing.py` exists, so risk classification alone works
+without routing being installed.
+
+Create the three labels once (or let them be auto-created on first run):
+
+```bash
+for level in low medium high; do
+  gh label create "risk:$level" --color "$(case $level in
+    high) echo b60205 ;; medium) echo fbca04 ;; low) echo 0e8a16 ;;
+  esac)" --description "PR risk: $level" --force
+done
+```
+
+Commit the workflow and config. The first PR you open afterwards triggers
+the action.
+
+## Customize
+
+Edit `.github/pr-risk-config.yml`:
+
+- **Add** patterns to `high` for paths where review must be careful
+  (payment code, tenant boundaries, feature flags you care about).
+- **Add** patterns to `medium` for shared services, public endpoints,
+  non-critical jobs.
+- **Add** patterns to `ignore` for paths that should never influence the
+  level (docs, generated files, snapshot tests).
+
+Matching uses `fnmatch` glob syntax (`**/auth/**`, `composer.lock`, …).
+
+If you do not want a config file, delete it — the script falls back to
+defaults that cover migrations, lockfiles, auth, workflows, and infra
+across Laravel, Symfony, Django, Rails, Node, and Next.js.
+
+## What the PR comment looks like
+
+```
+## 🟡 PR Risk: medium
+
+_14 changed file(s), 2 risk signal(s)._
+
+### 🟡 Medium
+- `**/app/Http/Controllers/**` — 2 file(s)
+  - `app/Http/Controllers/Api/OrderController.php`
+  - `app/Http/Controllers/Api/PaymentController.php`
+- `composer.json` — 1 file(s)
+  - `composer.json`
+
+---
+_Classifier is heuristic. Merge is not blocked by this check._
+```
+
+The same comment is **updated** (not re-posted) on every new push thanks
+to `marocchino/sticky-pull-request-comment`.
+
+## Routing comment format
+
+```
+## 🔴 Review Routing: high
+
+_3 changed file(s), 2 historical pattern(s) matched._
+
+### Suggested reviewers (role-based)
+- primary:   finance-engineering — focus: tax calculation + idempotency
+- secondary: security            — focus: tax calculation + idempotency
+
+### Historical patterns matched
+- 🔴 queue-job-not-idempotent — Queue job without idempotency key
+    required test: assert a retried job does not double-write
+- 🔴 blade-unsafe-html        — Blade component renders user input with {!! !!}
+
+_Data source: ownership-map.yml + historical-bug-patterns.yml. …_
+```
+
+Curate `ownership-map.yml` and `historical-bug-patterns.yml` over time —
+see `.augment/guidelines/agent-infra/review-routing-data-format.md` for
+the full schema.
+
+## Uninstall
+
+```bash
+rm .github/workflows/pr-risk-review.yml
+rm scripts/pr_risk_review.py
+rm scripts/pr_review_routing.py
+rm .github/pr-risk-config.yml .github/ownership-map.yml .github/historical-bug-patterns.yml
+gh label delete risk:low risk:medium risk:high
+```
+
+## Verifying locally
+
+```bash
+python3 scripts/pr_risk_review.py \
+  --base origin/main --head HEAD \
+  --config .github/pr-risk-config.yml \
+  --output /tmp/risk-report.md \
+  --level-file /tmp/risk-level.txt
+
+python3 scripts/pr_review_routing.py \
+  --base origin/main --head HEAD \
+  --ownership-map .github/ownership-map.yml \
+  --patterns .github/historical-bug-patterns.yml \
+  --output /tmp/routing-report.md \
+  --level-file /tmp/routing-level.txt
+
+cat /tmp/risk-report.md /tmp/routing-report.md
+```
+
+## Limitations
+
+- **Heuristic only.** A PR with no matched patterns is labeled `low` even
+  if it changes business-critical logic. Reviewers still need to read.
+- **No semantic analysis.** The classifier looks at paths, not diff
+  content. A whitespace-only edit to `composer.lock` is still `high`.
+- **Not a policy engine.** Use CODEOWNERS + required reviews for
+  enforcement; use this workflow for triage and discussion.
+
+---
+
+# Memory Hygiene — installation
+
+Weekly staleness report for the four engineering-memory files under
+`agents/memory/`. Opens (or updates) a single tracking issue with the
+`memory-hygiene` label when entries are past their
+`review_after_days` window. Closes the issue automatically once all
+entries are fresh again. Purely informational — it does **not** block
+PRs.
+
+## What gets installed
+
+| File in package | Copy to | Purpose |
+|---|---|---|
+| `templates/github-workflows/memory-hygiene.yml` | `.github/workflows/memory-hygiene.yml` | Weekly staleness workflow |
+| `templates/scripts/check_memory.py` | `scripts/check_memory.py` | YAML schema + staleness validator |
+
+## Install
+
+```bash
+# from the consumer repo root
+cp .augment/templates/github-workflows/memory-hygiene.yml .github/workflows/
+cp .augment/templates/scripts/check_memory.py            scripts/
+```
+
+Commit both. The first scheduled run (Mondays 06:00 UTC) reports on
+whatever is under `agents/memory/`. Trigger manually with
+`gh workflow run memory-hygiene.yml`.
+
+## Verifying locally
+
+```bash
+python3 scripts/check_memory.py --path agents/memory
+```
+
+Exit `0` = clean, `1` = violations (missing required fields, duplicate
+ids, or obvious secrets — staleness alone is informational).
+
+Schema reference: `.augment/guidelines/agent-infra/engineering-memory-data-format.md`.
+Schema examples: `.augment/templates/agents/memory/*.example.yml`.