@event4u/agent-config 1.9.1

package/.agent-src/templates/copilot-instructions.md

@@ -0,0 +1,115 @@
+# Copilot Repository Instructions
+
+<!--
+  copilot-instructions.md — read by GitHub Copilot Code Review (PR bot) and
+  Copilot Chat when reviewing or editing this repo.
+
+  This file was installed by `event4u/agent-config` as a starting template.
+  Fill in the placeholders below and remove this HTML comment.
+
+  Keep this file **self-contained**. Copilot Code Review CANNOT follow links
+  to `.augment/` — so every rule Copilot must enforce lives here in full.
+  Copilot Chat (in the IDE) can read other files, but still benefits from
+  this overview.
+-->
+
+This repository contains {{project_description_oneline}}.
+
+> **For Copilot Chat users:** Deeper context lives in `.augment/` (skills,
+> rules, guidelines) and `AGENTS.md`. The instructions below are
+> self-contained for Copilot Code Review.
+>
+> For most tickets — feature, bug fix, or refactor — start with
+> `/implement-ticket` (see `.augment/commands/implement-ticket.md`). It drives
+> the linear flow `refine → memory → analyze → plan → implement → test →
+> verify → report`, blocks on ambiguity instead of guessing, and never
+> commits, pushes, or opens PRs on its own.
+
+## ✅ Scope Control
+
+- Do not introduce architectural changes unless explicitly requested.
+- Do not replace existing patterns with alternatives.
+- Do not suggest new libraries unless explicitly requested.
+- Stay within the established project structure.
+
+## ✅ Architecture
+
+<!-- Describe your layering. Example for a Laravel project:
+  - Controllers thin, no business logic
+  - Business logic in Service classes
+  - Validation in FormRequests
+  - Authorization in Policies
+-->
+
+{{architecture_notes}}
+
+## ✅ Coding Standards
+
+<!-- Language-specific standards. Keep them concrete and enforceable.
+  Examples:
+  - PHP: declare(strict_types=1), typed properties, constructor promotion
+  - TypeScript: strict mode, no `any`, prefer `readonly`
+  - Python: type hints on public APIs, `from __future__ import annotations`
+-->
+
+{{coding_standards}}
+
+## ✅ Framework Conventions
+
+<!-- Framework-specific patterns your team follows.
+  Examples:
+  - Laravel: Policies over Gates, Resource classes, Eloquent relationships
+  - Next.js: Server components by default, client components explicitly marked
+  - Rails: Service objects for complex logic
+-->
+
+{{framework_conventions}}
+
+## ✅ Testing
+
+- Test framework: **{{test_framework}}**
+- Run all tests: `{{test_all_command}}`
+- Run targeted tests: `{{test_targeted_command}}`
+
+{{testing_extra_notes}}
+
+## ✅ Legacy / Existing Code Handling
+
+- Do NOT refactor existing code solely to comply with these rules.
+- Only modify existing code if directly related to the current change,
+  bug fix, security, or explicitly requested.
+- New or newly modified code MUST follow all rules in this document.
+
+## ✅ Code Review Scope
+
+- Review **only the actually modified lines** and their direct dependencies.
+- Do NOT review or suggest changes to unmodified code in the same file.
+- Do NOT nitpick style issues that linters/formatters auto-fix.
+
+## ✅ Code Review Comment Behavior
+
+- **Never create duplicate comments** — one comment per concern per location.
+- **Never re-raise rejected suggestions** — if the developer said no, accept it.
+- Answer questions concisely; do not argue.
+- Resolve conversations once the issue is addressed.
+
+## ✅ Language Rules
+
+- Code comments: English.
+- Parameter / variable / method / class names: English.
+- Commit messages: English, Conventional Commits.
+- User-facing strings: {{user_facing_strings_strategy}}
+
+## ✅ Package Management
+
+- Always use the package manager (`composer require`, `npm install`,
+  `pip install`) — never hand-edit `composer.json`, `package.json`, or
+  `requirements.txt`. The manager handles version resolution and lock files.
+
+## ✅ Copilot Behavior
+
+- Generate {{target_language_level}} code only — avoid features from newer
+  versions unless the project has upgraded.
+- Prioritize **readable, clean, maintainable** code over cleverness.
+- Default to **immutability**, **dependency injection**, and **encapsulation**.
+- Be direct and concise — no "Sure!", "You're right!" or similar filler.

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

@@ -0,0 +1,125 @@
+# Feature Planning Template
+
+Templates for feature plan files stored in `agents/features/` or `app/Modules/{Module}/agents/features/`.
+
+---
+
+## Rules for Feature Plans
+
+1. **Collaborative.** Feature plans are created interactively with the user, not auto-generated.
+2. **Decision-focused.** Capture problems, proposals, scope, and tradeoffs — not implementation steps.
+3. **Linked.** Reference affected modules, related features, and generated roadmaps.
+4. **Language:** All feature plans must be written in **English**.
+5. **One feature per file.** Don't combine unrelated features.
+6. **Keep it concise.** Aim for 100–300 lines. If larger, the feature should be split.
+
+---
+
+## Status Values
+
+| Emoji | Status | Meaning |
+|---|---|---|
+| 💡 | Idea | Rough concept, not yet validated |
+| 🔍 | Exploring | Being researched and brainstormed |
+| 📋 | Planned | Structured plan complete, ready for roadmap |
+| 🗺️ | Roadmapped | Roadmap(s) generated, ready for implementation |
+| 🔄 | In Progress | Implementation started |
+| ✅ | Complete | Feature shipped |
+| ❌ | Rejected | Decided not to build |
+| ⏸️ | On Hold | Paused for external reasons |
+
+---
+
+## Template
+
+Copy the structure below into a new file:
+
+```markdown
+# Feature: {title}
+
+> {One sentence: What does this feature do and why?}
+
+**Status:** 💡 Idea
+**Created:** {YYYY-MM-DD}
+**Author:** {name}
+**Jira:** {ticket/epic links or "none" — e.g. [DEV-1234]({JIRA_BASE_URL}/browse/DEV-1234)}
+**Module:** {module name or "project-wide"}
+**Context:** {path to context document or "none"}
+
+## Problem
+
+{What pain point does this solve? Who is affected? What happens today without this feature?}
+
+## Proposal
+
+{What's the proposed solution? Keep it high-level — describe the outcome, not the implementation.}
+
+## Scope
+
+### In Scope
+
+- {What this feature includes}
+- {Specific functionality}
+
+### Out of Scope (deferred)
+
+- {What this feature does NOT include}
+- {Features to consider later}
+
+## Affected Areas
+
+| Area | Impact |
+|---|---|
+| Module: {name} | {what changes} |
+| Model: {name} | {new fields, relationships} |
+| API: {endpoint} | {new/changed endpoints} |
+| UI: {view/component} | {new/changed views} |
+| Migration | {schema changes} |
+
+## Technical Approach
+
+{High-level architecture decisions. Which patterns to follow? Which existing services to extend?
+Reference existing code where helpful.}
+
+### Options Considered
+
+| Option | Pros | Cons | Decision |
+|---|---|---|---|
+| {Option A} | {pros} | {cons} | ✅ Chosen / ❌ Rejected |
+| {Option B} | {pros} | {cons} | ✅ Chosen / ❌ Rejected |
+
+## Open Questions
+
+- [ ] {Unresolved question 1}
+- [ ] {Unresolved question 2}
+
+## Dependencies
+
+- {Other features or changes this depends on}
+- {External services or packages needed}
+
+## Acceptance Criteria
+
+- [ ] {Measurable outcome 1}
+- [ ] {Measurable outcome 2}
+- [ ] All quality gates pass (PHPStan, Rector, tests)
+
+## Roadmaps
+
+_No roadmaps generated yet. Run `/feature-roadmap` to create implementation roadmaps._
+
+## Notes
+
+{Optional: edge cases, risks, references, related discussions.}
+```
+
+---
+
+## Tips
+
+- **Start with the Problem.** If you can't articulate the problem, the feature isn't ready.
+- **Be specific in Scope.** "Out of Scope" is as important as "In Scope".
+- **List Affected Areas early.** This helps estimate effort and identify risks.
+- **Use Options Considered.** Document why you chose one approach over another.
+- **Link to code.** "See `app/Modules/Import/App/Services/ImportService.php`" is better than "the import service".
+

package/.agent-src/templates/github-workflows/memory-hygiene.yml

@@ -0,0 +1,133 @@
+# Memory Hygiene — template shipped by agent-config
+#
+# Copy this file to `.github/workflows/memory-hygiene.yml` in the consumer
+# project. It runs `scripts/check_memory.py` on a weekly schedule and
+# opens (or updates) a single tracking issue when stale entries are
+# found in `agents/memory/`.
+#
+# This workflow is intentionally **not** wired into PR checks — staleness
+# is a review signal, not a merge blocker. See
+# `road-to-engineering-memory.md` Phase 4 for the rationale.
+#
+# Prerequisites:
+#   - `scripts/check_memory.py` copied from
+#     `.augment/templates/scripts/check_memory.py` into the consumer repo.
+#   - At least one file exists under `agents/memory/` — absence short-
+#     circuits the job with an informational log, no issue opened.
+
+name: Memory Hygiene
+
+on:
+  schedule:
+    # Every Monday at 06:00 UTC — run AFTER the weekly retro window.
+    - cron: "0 6 * * 1"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  check-staleness:
+    name: Report stale memory entries
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install PyYAML
+        run: pip install pyyaml
+
+      - name: Short-circuit if no memory files
+        id: has_memory
+        run: |
+          if [ -d "agents/memory" ] && [ "$(find agents/memory -name '*.yml' | wc -l)" -gt 0 ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            echo "No agents/memory/*.yml files — skipping."
+          fi
+
+      - name: Run staleness check
+        if: steps.has_memory.outputs.present == 'true'
+        id: check
+        run: |
+          set +e
+          {
+            echo "## Memory hygiene report"
+            echo
+            echo '```'
+            python3 scripts/check_memory.py --path agents/memory
+            exit_code=$?
+            echo '```'
+          } > staleness.md
+          echo "exit=${exit_code:-0}" >> "$GITHUB_OUTPUT"
+          cat staleness.md
+
+      - name: Find existing tracking issue
+        if: steps.has_memory.outputs.present == 'true'
+        id: find_issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: "open",
+              labels: "memory-hygiene",
+              per_page: 5,
+            });
+            if (issues.length > 0) {
+              core.setOutput("number", issues[0].number);
+            }
+
+      - name: Open or update tracking issue
+        if: steps.has_memory.outputs.present == 'true' && steps.check.outputs.exit != '0'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs");
+            const body = fs.readFileSync("staleness.md", "utf8");
+            const title = "Memory Hygiene — stale entries detected";
+            const existing = "${{ steps.find_issue.outputs.number }}";
+            if (existing) {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: parseInt(existing, 10),
+                body,
+              });
+            } else {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body,
+                labels: ["memory-hygiene"],
+              });
+            }
+
+      - name: Close tracking issue when clean
+        if: steps.has_memory.outputs.present == 'true' && steps.check.outputs.exit == '0' && steps.find_issue.outputs.number != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: parseInt("${{ steps.find_issue.outputs.number }}", 10),
+              state: "closed",
+              state_reason: "completed",
+            });
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: parseInt("${{ steps.find_issue.outputs.number }}", 10),
+              body: "All memory entries are fresh — closing.",
+            });

package/.agent-src/templates/github-workflows/pr-risk-review.yml

@@ -0,0 +1,123 @@
+# PR Risk Review — template shipped by agent-config
+#
+# Copy this file to `.github/workflows/pr-risk-review.yml` in the consumer
+# project. It posts (or updates) a single sticky comment on every PR with a
+# heuristic risk classification (low / medium / high) based on the list of
+# changed files.
+#
+# Behavior is driven by `.github/pr-risk-config.yml` (see the example file
+# under `.augment/templates/scripts/pr-risk-config.example.yml`). Without a
+# config file the script falls back to sensible cross-stack defaults.
+#
+# This workflow is purely informational — it does NOT block merges. Gate the
+# PR on a separate required check if you want a hard stop.
+
+name: PR Risk Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  risk-review:
+    name: Classify PR risk
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Classify risk
+        id: risk
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          python3 scripts/pr_risk_review.py \
+            --base "$BASE_SHA" \
+            --head "$HEAD_SHA" \
+            --config .github/pr-risk-config.yml \
+            --output risk-report.md \
+            --level-file risk-level.txt
+
+          echo "level=$(cat risk-level.txt)" >> "$GITHUB_OUTPUT"
+
+      - name: Post or update sticky PR comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-risk-review
+          path: risk-report.md
+
+      - name: Apply risk label
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const level = `${{ steps.risk.outputs.level }}`;
+            if (!['low', 'medium', 'high'].includes(level)) return;
+
+            const prNumber = context.payload.pull_request.number;
+            const desired = `risk:${level}`;
+            const labels = ['risk:low', 'risk:medium', 'risk:high'];
+
+            const { data: existing } = await github.rest.issues.listLabelsOnIssue({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+            });
+
+            for (const lbl of existing) {
+              if (labels.includes(lbl.name) && lbl.name !== desired) {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  name: lbl.name,
+                });
+              }
+            }
+
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              labels: [desired],
+            });
+
+      - name: Classify review routing
+        id: routing
+        if: hashFiles('scripts/pr_review_routing.py') != ''
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        # The script auto-discovers ownership-map.yml and
+        # historical-bug-patterns.yml under .github/ first and falls
+        # back to agents/ — matching the review-routing-awareness rule.
+        # Missing data files emit a generic fallback, not an error.
+        run: |
+          python3 scripts/pr_review_routing.py \
+            --base "$BASE_SHA" \
+            --head "$HEAD_SHA" \
+            --output routing-report.md \
+            --level-file routing-level.txt
+
+      - name: Post or update routing sticky comment
+        if: steps.routing.outcome == 'success'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-review-routing
+          path: routing-report.md

package/.agent-src/templates/github-workflows/proposal-drift.yml

@@ -0,0 +1,118 @@
+# Proposal Drift — template shipped by agent-config
+#
+# Copy this file to `.github/workflows/proposal-drift.yml` in the PACKAGE
+# repo (event4u/agent-config itself). It runs weekly and posts an
+# imbalance report when the number of accepted upstream proposals in the
+# last quarter diverges from the number of retired rules/skills.
+#
+# Rationale: the curated self-improvement pipeline can only work if
+# **additions and retirements stay roughly in balance**. A repo that
+# only accepts new proposals without ever retiring anything drifts
+# towards noise; a repo that only retires without accepting drifts
+# towards stagnation. See `road-to-curated-self-improvement.md`
+# Phase 4 for the full framing.
+#
+# This workflow is intentionally read-only — it never blocks a PR and
+# never modifies the repo. It only opens / updates a tracking issue.
+#
+# Prerequisites:
+#   - `scripts/memory_report.py` present in the repo (ships with the
+#     package).
+#   - Proposals live under `agents/proposals/` with the schema defined
+#     in `.agent-src/templates/agents/proposal.example.md`.
+
+name: Proposal Drift
+
+on:
+  schedule:
+    # Every Monday at 07:00 UTC — one hour after memory-hygiene so the
+    # two issues do not land in the same notification batch.
+    - cron: "0 7 * * 1"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  drift-report:
+    name: Accepted vs. retired proposals
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install PyYAML
+        run: pip install pyyaml
+
+      - name: Build quarterly report
+        id: report
+        run: |
+          set +e
+          {
+            echo "## Proposal drift report"
+            echo
+            echo "Accepted vs. retired for the last quarter."
+            echo
+            echo '```'
+            python3 scripts/memory_report.py --quarterly --format text
+            echo '```'
+            echo
+            echo "Open proposals by stage:"
+            echo
+            echo '```'
+            find agents/proposals -name '*.md' 2>/dev/null | \
+              xargs -I{} grep -H '^stage:' {} 2>/dev/null | \
+              awk -F: '{print $3}' | sort | uniq -c || true
+            echo '```'
+          } > drift.md
+          cat drift.md
+
+      - name: Find existing tracking issue
+        id: find_issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: "open",
+              labels: "proposal-drift",
+              per_page: 5,
+            });
+            if (issues.length > 0) {
+              core.setOutput("number", issues[0].number);
+            }
+
+      - name: Open or update tracking issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs");
+            const body = fs.readFileSync("drift.md", "utf8");
+            const title = "Proposal Drift — weekly report";
+            const existing = "${{ steps.find_issue.outputs.number }}";
+            if (existing) {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: parseInt(existing, 10),
+                body,
+              });
+            } else {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body,
+                labels: ["proposal-drift"],
+              });
+            }

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

@@ -0,0 +1,24 @@
+# Override: Command — {command-name}
+
+> Override for `.augment/commands/{command-name}.md`
+
+---
+**Mode:** `extend` | `replace`
+**Original:** `.augment/commands/{command-name}.md`
+---
+
+<!-- MODE EXPLANATION:
+  - extend:  The original command is loaded FIRST, then this file modifies specific steps or adds new ones.
+             Use this to inject project-specific steps, change prompts, or add constraints.
+  - replace: The original command is IGNORED entirely. This file defines the full command flow.
+             Use this when the original command flow does not fit the project at all.
+-->
+
+## Modified Steps
+
+<!-- For mode: extend — list only the steps that change. Reference original steps by number/name. -->
+
+## Full Command Flow
+
+<!-- For mode: replace — write the complete command definition from scratch. -->
+

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

@@ -0,0 +1,21 @@
+# Override: Guideline — {guideline-name}
+
+> Override for `.augment/guidelines/{path}/{guideline-name}.md`
+
+---
+**Mode:** `extend` | `replace`
+**Original:** `.augment/guidelines/{path}/{guideline-name}.md`
+---
+
+<!-- MODE EXPLANATION:
+  - extend:  The original guideline is loaded FIRST, then this file adds to or modifies specific sections.
+             Use this to add project-specific conventions, extra examples, or stricter rules.
+  - replace: The original guideline is IGNORED entirely. This file is the sole source of truth.
+             Use this when the project's conventions differ fundamentally from the shared guideline.
+-->
+
+## Overridden Sections
+
+<!-- For mode: extend — only list what changes. Reference original sections by heading. -->
+<!-- For mode: replace — write the complete guideline from scratch. -->
+

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

@@ -0,0 +1,19 @@
+# Override: Rule — {rule-name}
+
+> Override for `.augment/rules/{rule-name}.md`
+
+---
+**Mode:** `extend` | `replace`
+**Original:** `.augment/rules/{rule-name}.md`
+---
+
+<!-- MODE EXPLANATION:
+  - extend:  The original rule is loaded FIRST, then this file adds to or modifies specific parts.
+  - replace: The original rule is IGNORED entirely. This file is the sole source of truth.
+-->
+
+## Overridden Rules
+
+<!-- For mode: extend — only list what changes. Everything else stays as-is. -->
+<!-- For mode: replace — write the complete rule set from scratch. -->
+