@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/complexity-first-planning/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: complexity-first-planning
+description: "Use when staging multi-component or uncertain work — tackle the load-bearing unknown first (risk-first decomposition), not the easy parts first."
+source: package
+domain: engineering
+status: active
+model_tier: medium
+tier: senior
+context_spine: [repo]
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# complexity-first-planning
+
+Part of the Reasoning Discipline Protocol. Engage per
+[`rdp-gate`](../../contexts/execution/rdp-gate.md) (skip on trivial / linear
+tasks; light touch on a strong-reasoning host).
+
+> **Provenance.** This is an **RDP derivation from general engineering discipline
+> (risk-first / critical-path / pre-mortem)** — it is **not** an Anthropic-
+> documented Fable behavior. Fable's "start at the top of your difficulty range"
+> is about *task selection* (give the model harder tasks), not intra-task order.
+> The skill stands on its own merit; it is not sold as a frontier-model transplant.
+
+## When to use
+
+- Staging multi-component work where the hardest/most-uncertain part is not yet proven.
+- A plan whose later steps depend on an assumption that could collapse.
+
+Do NOT use for single-step, linear, or fully-specified tasks (no load-bearing
+unknown to resolve), or when the user has already fixed the sequence.
+
+## When the agent should load this
+
+- The user asks to "plan", "break down", or "stage" work that spans ≥2 components
+  and at least one part is unproven.
+- A multi-step plan is forming whose later steps assume something untested.
+- Mid-task: a step just failed because an earlier, easier step baked in a wrong
+  assumption — reload this and re-sequence risk-first.
+
+## Procedure
+
+1. **Inspect and name the unknowns.** Read the affected components first, then
+   list which carry real uncertainty (technical feasibility, an unverified
+   integration, an ambiguous requirement) — analyze the existing system before
+   planning any change.
+2. **Assess and rank by load-bearing risk.** The load-bearing unknown is the one
+   whose failure invalidates the most dependent work — not the one that is merely hard.
+3. **Resolve it first.** Spike / probe / prototype the load-bearing unknown
+   before building anything that depends on it. Record the result in the notes
+   file (see [`notes-first-reasoning`](../../rules/notes-first-reasoning.md)):
+   prediction → result → lesson.
+4. **Cascade.** Once the riskiest assumption holds (or is corrected), sequence
+   the dependent work. If it fails, the cheap early failure saved the rework.
+
+## Output
+
+A short ordered plan that leads with the load-bearing unknown + how it will be
+proven, then the dependent steps. One recommendation, not a survey.
+
+## Do NOT
+
+- Build the easy parts first to show progress, then discover the hard part breaks them.
+- Treat "hardest" as "most code" — rank by *dependency blast radius*, not effort.
+- Over-plan a strong-reasoning host (it sequences risk natively — keep it light).
+
+## Gotchas
+
+- **Mistaking effort for risk.** A 400-line but well-understood refactor is *low*
+  load-bearing risk; a 5-line call into an unverified third-party API is *high*.
+  Ranking by size instead of dependency blast radius is the classic failure.
+- **"Resolved on paper".** Reasoning that the unknown "should work" is not
+  resolving it — the spike must actually run / compile / return before dependent
+  work starts. Record prediction → result, not prediction → assumption.
+- **Spike sprawl.** The probe answers exactly one question (does the load-bearing
+  assumption hold?), then stops. Turning it into the real implementation defeats
+  the cheap-early-failure purpose.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Staging multi-component work where the hardest / most-uncertain part is unproven.
+- A plan whose later steps rest on an assumption that could collapse.
+
+**WHEN NOT to use this**
+
+- Single-step, linear, or fully-specified work — no load-bearing unknown to
+  resolve; the [`rdp-gate`](../../contexts/execution/rdp-gate.md) filters these.
+- Breaking a feature into tasks in general — route to
+  [`feature-planning`](../feature-planning/SKILL.md), which composes this skill.
+- Recording the spike's prediction / result / lesson — that belongs in
+  [`notes-first-reasoning`](../../rules/notes-first-reasoning.md).

package/dist/agent-src/skills/complexity-first-planning/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "complexity-first-planning",
+  "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers multi-component / uncertain work where a load-bearing unknown must be resolved first; should-not covers trivial / linear / fully-sequenced work and neighbors (feature breakdown, simple tests).",
+  "queries": [
+    {"q": "build a multi-tenant reporting pipeline with caching and access control — where do I start?", "trigger": true},
+    {"q": "we need to migrate auth to OAuth and we're not sure the legacy token format maps cleanly", "trigger": true},
+    {"q": "stage this feature so we fail fast on the riskiest part", "trigger": true},
+    {"q": "the plan depends on the new vector DB actually handling our query latency — sequence the work", "trigger": true},
+    {"q": "which part of this 6-step build should we tackle first?", "trigger": true},
+    {"q": "add a unit test for the existing slugify() helper", "trigger": false, "note": "single linear step — no load-bearing unknown"},
+    {"q": "rename this method across the codebase", "trigger": false, "note": "mechanical, fully specified"},
+    {"q": "break this epic into tickets", "trigger": false, "note": "feature-planning breakdown, not risk-first ordering"},
+    {"q": "fix the typo in the README", "trigger": false, "note": "trivial"},
+    {"q": "implement steps 1 through 4 in the order I listed", "trigger": false, "note": "user already fixed the sequence"}
+  ]
+}

package/dist/agent-src/skills/condense-memory/SKILL.md

@@ -0,0 +1,123 @@
+---
+model_tier: inherit
+name: condense-memory
+description: "Use when shrinking always-loaded memory files (AGENTS.md, CLAUDE.md, .cursorrules) via telegraph grammar — refuses sensitive paths, round-trips via .original.md backup."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: [Bash]
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# condense-memory
+
+> **Experimental.** Output-side telegraph dialect did not meet kill-criterion in [`internal/bench/reports/telegraph-v1.md`](../../../bench/reports/telegraph-v1.md) (`vs_terse` median −9.27 %). Input-side memory condensation is orthogonal use case: savings target always-loaded memory budget, not reply stream. Treat ship-criterion as **per-target measurement**, not v1 verdict.
+
+## When to use
+
+Use when:
+
+- Always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`) close to or above host tool's char budget and maintainer wants to recover input-token headroom.
+- Consumer-shipped `templates/AGENTS.md` failing `agents-md-thin-root` cap and pointer-extraction options exhausted.
+- Maintainer asks to "condense this memory file" or "shrink AGENTS.md" or names input-side telegraph.
+
+## Do NOT
+
+- Condense reply, commit message, PR body, ticket summary, or any deliverable written *for* human reader — those are carve-outs in [`telegraph-speak § Carve-outs`](../../rules/telegraph-speak.md) and stay verbatim.
+- Condense path matching sensitive-file denylist (`.env*`, `.netrc`, `credentials*`, `secrets*`, `id_rsa*`, `*.pem|key|p12|pfx|crt|cer|jks`, `.ssh/*`) — script refuses with `SensitivePathError` and so should you.
+- Condense generated file (`dist/agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`) — edit source in `.agent-src.uncondensed/` and regenerate via package's sync + generate-tools scripts (`scripts/condense.sh --sync` + `scripts/condense.py --generate-tools`).
+- Hand-edit condensed memory file in place — run `--decondense` first; next condense pass refuses on body-hash drift (`CondensationRefused`).
+- Commit condensed file without committing matching `.original.md` backup — round-trip breaks otherwise.
+
+## Procedure
+
+1. **Analyse target first.** Before any write, **inspect** target with `view` or `wc -l` to confirm it is always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`), not generated, and has prose paragraphs to condense (pointer-only Thin-Root file may net near-zero). Skip rest of procedure if any check fails.
+2. **Check denylist gate.** Run `python3 scripts/condense_memory.py <path> --check` — exit 0 = safe; exit 2 = denylist hit, stop and surface refusal.
+3. **Record baseline.** `wc -c <path>` — capture pre-condensation char count for commit message.
+4. **Condense.** `python3 scripts/condense_memory.py <path>`. Script writes `<path>.original.md` (verbatim backup) and rewrites `<path>` with `original_sha256:` + `condensed_at:` frontmatter.
+5. **Inspect diff.** Eyeball every Iron-Law fence, numbered-options block, code fence, backtick span, `❌`/`⚠️`/`✅` line, and frontmatter pair — all must be byte-identical. Body prose may have lost articles (`the`/`a`/`an`) and auxiliaries (`is`/`are`/`was`/`be`/`that`/`which`).
+6. **Validate idempotency.** Re-run `python3 scripts/condense_memory.py <path>` — clean re-run is no-op (body hash matches). Non-zero exit = stop, escalate.
+7. **Commit both files together.** `<path>` and `<path>.original.md` ship as pair. Backup is rollback path; never commit one without other.
+8. **Rollback path.** If readability fails review at step 5: `python3 scripts/condense_memory.py <path> --decondense` restores backup and deletes `.original.md`.
+
+## Output format
+
+Maintainer-facing report after invoking script MUST contain, in this order:
+
+1. **Diff line** — pre/post `wc -c` as single line (`AGENTS.md: 2,891 → 2,453 chars (−15.1 %)`).
+2. **Backup path** — full path of `.original.md` backup so maintainer can verify it landed on disk.
+3. **Carve-out check** — one line confirming seven carve-out classes round-tripped (`carve-outs: 7 classes preserved · idempotent re-run: clean`).
+4. **Exit-code surface** — on failure, surface verbatim exit code and exception name (`SensitivePathError → exit 2`, `CondensationRefused → exit 3`, `FileNotFoundError → exit 4`); do not paraphrase.
+
+Do **not** narrate algorithm, grammar rules, or carve-out theory — rule and this skill document contract; output reports result.
+
+## Carve-outs — byte-for-byte preserved
+
+Mirrors seven carve-out classes in [`telegraph-speak`](../../rules/telegraph-speak.md). Condensation engine in [`scripts/condense_memory.py`](../../../scripts/condense_memory.py) preserves:
+
+1. **Triple-backtick fences** — any language, any depth.
+2. **Numbered-options lines** — `^>?\s*\d+\.\s` plus `**Recommendation:**` / `**Empfehlung:**` label.
+3. **Backtick spans** — file paths, command names, identifiers inside body prose.
+4. **Status / error markers** — lines starting with `❌`, `⚠️`, `✅`.
+5. **Iron-Law ALL-CAPS lines** — `^[A-Z][A-Z0-9 ,.\-_/']{3,}$`.
+6. **Frontmatter blocks** — `---` fence pairs at head of file.
+7. **Mode markers** per [`role-mode-adherence`](../../rules/role-mode-adherence.md).
+
+Mangling any of these breaks Iron-Law surface host tool reads. Unit tests in `tests/test_condense_memory.py` lock each carve-out class as regression case.
+
+## Idempotency contract — Step 9 guard
+
+Script is **idempotent on clean re-runs**: running it twice on same target is no-op because body hash matches recondensed hash. Script **refuses** on **body drift**:
+
+| State | Outcome |
+|---|---|
+| No frontmatter SHA marker | Condense + write backup + inject SHA. |
+| SHA marker present, body re-condenses to same hash | No-op (return target unchanged). |
+| SHA marker present, body hash diverged | **Refuse** with `CondensationRefused` exit 3. |
+
+If you need to edit condensed memory file, run `--decondense` first, edit restored `.original.md` content, then re-run condenseor. Never hand-edit condensed body — next CI run will either silently corrupt your edit (if it happens to re-condense to same shape) or hard-fail next condense pass.
+
+## Sensitive-path gate
+
+Every read path passes through [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) `assert_safe()` before bytes leave disk. Gate is security floor for Phase 2 (input-side condensation) per `step-16-telegraph-substance.md` Phase 0; rollback of gate is rollback of this skill.
+
+CLI exit codes:
+
+- `0` — condense / decondense / check succeeded.
+- `2` — `SensitivePathError` (path matched denylist).
+- `3` — `CondensationRefused` (body hash diverged from frontmatter SHA).
+- `4` — `FileNotFoundError` (no `.original.md` backup to restore).
+
+## Gotchas
+
+- **Body-hash drift after manual edit** — hand-editing condensed body breaks `original_sha256:` invariant. Next condense pass refuses with `CondensationRefused` (exit 3). Recovery: `--decondense`, edit restored body, re-condense.
+- **`.original.md` backup missing on `--decondense`** — exit 4 (`FileNotFoundError`). Either someone deleted backup or `--decondense` already ran. Restore from git history; never regenerate backup by hand (regenerated content would not be byte-identical).
+- **Denylist false positive** — sensitive-looking filename outside denylist surface (project-specific naming) will still pass `assert_safe()`. Denylist necessary but not sufficient; maintainer responsible for never feeding secrets to condenseor.
+- **Frontmatter ordering with existing keys** — if target already has frontmatter, condenseor preserves existing keys, drops any prior `original_sha256:` / `condensed_at:` entries, and appends new pair. Other agents reading file should treat SHA + timestamp pair as canonical condensation marker, not file size.
+- **Negative savings on pointer-heavy files** — `templates/AGENTS.md` already following Thin-Root (≥ 40 % pointers, ≥ 60-char *why*-clauses) has little prose left to drop; condensation may net near-zero or even add bytes via frontmatter. Run [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) first to maximise pointer share, then measure whether this skill still pays.
+- **Generated-tree drift** — condensing `.agent-src.uncondensed/templates/AGENTS.md` does NOT propagate to `.augment/`, `.claude/`, etc. until package's sync + generate-tools scripts run (`scripts/condense.sh --sync` + `scripts/condense.py --generate-tools`). Always regenerate after condensing templated file.
+
+## Measurement — when to condense
+
+No published `telegraph-v2` baseline for input-side savings yet (Step 11 of `step-16-telegraph-substance.md` ships that). Until then, maintainer judges per-target whether condensation pays its readability cost. Suggested workflow:
+
+1. `wc -c <path>` before — record baseline char count.
+2. `python3 scripts/condense_memory.py <path>` — condense + back up.
+3. `wc -c <path>` after — record post-condensation char count.
+4. Eyeball diff: does prose stay legible? Are all Iron-Law fences intact?
+5. If yes → commit both `<path>` and `<path>.original.md`. If no → `--decondense`.
+
+Future `telegraph-v2.md` will tabulate realised input-token saving against `agents-md-thin-root` 40 % pointer-ratio constraint so maintainer has numerical floor.
+
+## Cross-references
+
+- [`telegraph-speak`](../../rules/telegraph-speak.md) — runtime rule script mirrors for input-side targets; `telegraph.speak_scope` does **not** gate this script (input-side runs regardless).
+- [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) — Phase 0 gate; ported from upstream Telegraph `63a91ec`.
+- [`scripts/condense_memory.py`](../../../scripts/condense_memory.py) — implementation.
+- [`tests/test_condense_memory.py`](../../../tests/test_condense_memory.py) — regression locks for each carve-out + idempotency + denylist.
+- [`docs/contracts/condensation-default-kill-criterion.md`](../../../docs/contracts/condensation-default-kill-criterion.md) — v1 verdict (output-side; informs but does not gate this skill).
+- [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) — caps consumer-shipped `templates/AGENTS.md`; this skill is one tool to land under cap.

package/dist/agent-src/skills/context-document/SKILL.md

@@ -0,0 +1,160 @@
+---
+model_tier: inherit
+name: context-document
+description: "Use when the user says \"create context\", \"document this area\", or wants a structured snapshot of a codebase area for agent orientation."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# context
+
+## When to use
+
+Use this skill when:
+- Documenting a module, service, or integration for future reference
+- Exploring an unfamiliar area of the codebase
+- Preparing for a feature that touches multiple areas
+- Onboarding to a new part of the codebase
+
+
+Do NOT use when:
+- Writing code or features
+- Creating roadmaps (use `roadmap-management` skill)
+
+## Procedure: Manage contexts
+
+1. **Identify scope** — Which area of the codebase needs a context document?
+2. **Research** — Use codebase-retrieval to understand the area (files, patterns, dependencies).
+3. **Write or update** — Create/update the context doc following the template below.
+4. **Verify** — Confirm all referenced files exist and descriptions match current code.
+
+A **context document** is a structured snapshot of a codebase area:
+- What it does, why it exists
+- Key files, classes, and patterns
+- Database tables and API endpoints
+- Dependencies and known issues
+
+Unlike feature plans (future-focused) or roadmaps (task-focused), contexts are
+**present-focused** — they describe the current state of the code.
+
+## File structure
+
+```
+.augment/contexts/                       # Shared contexts (about the agent system itself)
+├── augment-infrastructure.md
+├── skills-and-commands.md
+└── documentation-hierarchy.md
+
+agents/settings/contexts/                         # Project-wide contexts
+├── {context-name}.md
+
+{module_root}/{Module}/{agent_folder}/settings/contexts/ # Module-scoped contexts
+├── {context-name}.md                                    # Laravel: app/Modules/…
+                                                         # Symfony: src/Bundle/…
+                                                         # Monorepo: packages/…
+
+.augment/templates/
+└── contexts.md                          # Context template
+```
+
+## Context types
+
+| Type | Scope | Example |
+|---|---|---|
+| **Module** | Single module's structure and purpose | `client-software.md` |
+| **Domain** | Business domain across modules | `import-pipeline.md` |
+| **Service** | Complex service with its deps | `customer-service.md` |
+| **Integration** | External API/system integration | `probaus-api.md` |
+| **Infrastructure** | DevOps or infrastructure concern | `queue-system.md` |
+
+## Where to store contexts
+
+| Content | Location |
+|---|---|
+| About the `.augment/` system itself | `.augment/contexts/` (shared package) |
+| Project-wide or cross-module | `agents/settings/contexts/` |
+| Module-specific | `{module_root}/{Module}/{agent_folder}/settings/contexts/` (resolved via `modules.root_paths` + `modules.agent_folder`; Laravel example: `app/Modules/{Module}/agents/settings/contexts/`) |
+| If unsure | Ask the user |
+
+### Shared vs. project-specific contexts
+
+**`.augment/contexts/`** — Part of the shared package. Describes the agent infrastructure:
+how overrides work, what skills/commands exist, the documentation hierarchy.
+These are read-only at project level (like all `.augment/` content).
+
+**`agents/settings/contexts/`** — Project-specific. Describes the project's business domain:
+modules, services, integrations, database architecture.
+These are created and maintained per project.
+
+## Integration with other systems
+
+### Sessions
+When working in an area that has a context document, load it at session start.
+The session's Context section can reference it.
+
+### Features
+Before planning a feature, check if a context document exists for the affected area.
+It provides the baseline understanding needed for planning.
+
+### Module exploration
+`/module-explore` gathers the data needed to create a module context.
+`/context-create` turns that exploration into a persistent document.
+
+### Overrides
+When customizing a shared skill or command, read `.augment/contexts/override-system.md` for the naming conventions and format.
+
+### Shared contexts
+When working on the agent infrastructure itself (skills, commands, rules), check
+`.augment/contexts/` for existing documentation about the system.
+
+## Behavior rules
+
+### Creating contexts
+
+1. **Always analyze the code first** — use `codebase-retrieval`, `view`, and file listing.
+2. **Be factual** — describe what IS, not what SHOULD be.
+3. **Be specific** — link to files, name classes, reference tables.
+4. **Ask the user** about anything unclear.
+
+### Maintaining contexts
+
+- Update `Last Updated` when modifying.
+- When code changes affect a context, update it.
+- `/context-refactor` is the dedicated command for this.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `context-create` | Analyze an area and create a new context document |
+| `context-refactor` | Revisit, update, and extend an existing context |
+
+
+## Output format
+
+1. Context document in the correct location with structured sections
+2. Cross-references to related contexts updated
+
+## Auto-trigger keywords
+
+- context document
+- codebase context
+- orientation doc
+- context creation
+
+## Gotcha
+
+- Context docs become stale — always check the actual code before trusting a context document.
+- Don't create context docs for areas that change weekly — they'll be outdated immediately.
+- Keep context docs factual, not aspirational — document what IS, not what should be.
+
+## Do NOT
+
+- Do NOT create contexts without analyzing the code first.
+- Do NOT guess about architecture — verify by reading the code.
+- Do NOT duplicate information from `AGENTS.md` — reference it instead.
+- Do NOT commit or push without permission.
+- Do NOT create contexts for trivial areas — only when the knowledge is worth persisting.

package/dist/agent-src/skills/copilot-config/SKILL.md

@@ -0,0 +1,207 @@
+---
+model_tier: medium
+name: copilot-config
+description: "Tune the GitHub Copilot AI — `copilot-instructions.md`, PR-review patterns, suggestion behavior, output verbosity. NOT for dev-environment setup (use `devcontainer`)."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Copilot Skill
+
+## When to use
+
+Use this skill when:
+- Editing `.github/copilot-instructions.md` to improve Copilot behavior
+- Dealing with Copilot PR review comments (via `/fix-pr-comments`)
+- Analyzing Copilot's review patterns to identify recurring false positives
+- Tuning Copilot's code suggestions for the project
+
+
+Do NOT use when:
+- Augment-specific behavior (use Augment rules and skills)
+- Writing application code
+
+## Procedure: Configure Copilot
+
+### Configuration File
+
+**`.github/copilot-instructions.md`** — the single source of truth for Copilot behavior.
+
+### What Copilot Can and Cannot Read
+
+| Context | Copilot Code Review (PR bot) | Copilot Chat (IDE) |
+|---|---|---|
+| `.github/copilot-instructions.md` | ✅ Reads automatically | ✅ Reads automatically |
+| `.augment/rules/` | ❌ Cannot access | ✅ Can read if referenced |
+| `.augment/skills/` | ❌ Cannot access | ✅ Can read if referenced |
+| `.augment/guidelines/` | ❌ Cannot access | ✅ Can read if referenced |
+| `AGENTS.md` | ❌ Cannot access | ✅ Can read if referenced |
+| `agents/` | ❌ Cannot access | ✅ Can read if referenced |
+
+**Key implication:** `copilot-instructions.md` must be **self-contained** for PR reviews.
+It cannot reference `.augment/` files and expect Copilot Code Review to follow them.
+For Copilot Chat users, a hint at the top of the file points to `.augment/` for deeper context.
+
+### What Copilot Controls
+
+| Area | How |
+|---|---|
+| Code suggestions | Follows coding standards, PHP 8.2 patterns, Laravel conventions |
+| PR reviews | Reviews only modified lines + direct dependencies |
+| Comment behavior | Deduplication rules, reply handling, scope control |
+| Language | English code comments, bilingual PR comments (EN + DE) |
+
+### Relationship to `.augment/`
+
+`copilot-instructions.md` and `.augment/` serve different audiences:
+
+| | `copilot-instructions.md` | `.augment/` |
+|---|---|---|
+| **Audience** | GitHub Copilot (bot + chat) | Augment Agent |
+| **Scope** | Coding standards, review rules | Full agent infrastructure |
+| **Self-contained?** | Yes (must be) | Yes (skills reference each other) |
+| **Duplication** | Intentional — Copilot can't read `.augment/` | No duplication needed |
+
+When updating coding rules, check if both files need the change:
+- **Architecture/coding rules** → update both (Copilot needs them self-contained)
+- **Agent workflows/commands** → only `.augment/` (Copilot doesn't use these)
+- **PR review behavior** → only `copilot-instructions.md` (Augment uses `/fix-pr-*` commands)
+
+## PR Review Comment Rules
+
+Copilot is configured with strict comment behavior rules:
+
+### Deduplication
+
+Before creating a comment, Copilot must:
+1. Check if it already commented on the same line/concern
+2. Check if another reviewer already raised the same point
+3. Skip if a duplicate would be created
+
+### Reply Handling
+
+| Developer response | Copilot action |
+|---|---|
+| Accepted suggestion | Acknowledge briefly or resolve |
+| Rejected with reason | Accept the decision, do NOT re-raise |
+| Asked a question | Answer with analysis and examples |
+| Dismissed without explanation | Move on, do NOT re-raise |
+
+### Key Principle
+
+**One comment per concern per location.** Never duplicate, never re-raise rejected suggestions.
+
+## Handling Copilot Bot Comments (as Augment Agent)
+
+When the user asks to fix Copilot's PR review comments (via `/fix-pr-comments`):
+
+### 1. Evaluate Each Comment
+
+For each Copilot comment, determine:
+
+| Category | Action |
+|---|---|
+| **Valid and actionable** | Fix the code as suggested |
+| **Valid but already handled** | Reply explaining it's already addressed (e.g., by ECS/Rector) |
+| **False positive** | Reply explaining why the suggestion doesn't apply |
+| **Style nitpick** | Reply that ECS/Rector handles this automatically |
+| **Out of scope** | Reply that the comment is outside the PR's change scope |
+
+### 2. Reply Format
+
+When replying to Copilot comments on behalf of the user:
+
+```markdown
+{English explanation}
+
+---
+
+🇩🇪 {German translation}
+```
+
+### 3. Common False Positives
+
+Copilot frequently suggests things that conflict with project conventions:
+
+| Copilot suggests | Project convention | Response |
+|---|---|---|
+| Add `null !== $var` with `is_string()` | `is_string()` already excludes null | False positive — redundant check |
+| Register events manually | Laravel 11 uses event discovery | Not needed since Laravel 11 |
+| Use `float` for money | Use `Math` helper class | Project uses BCMath via `Math::*()` |
+| Add PHPDoc repeating signature | Only add PHPDoc when types are insufficient | Redundant documentation |
+| Suggest `array()` syntax | Short syntax `[]` enforced by ECS | Auto-fixed by ECS |
+| Add `final` to mocked classes | Classes mocked by Mockery can't be final | Would break tests |
+
+## Improving Copilot Instructions
+
+When updating `.github/copilot-instructions.md`:
+
+### Structure
+
+- Each section starts with `## ✅ {Title}`
+- Rules are bullet points, concise and actionable
+- Code examples use `✅ Correct` / `❌ Wrong` pattern
+- Keep sections focused — one concern per section
+
+### When to Add New Rules
+
+| Trigger | Action |
+|---|---|
+| Copilot repeatedly makes the same wrong suggestion | Add to "Known Issues" section |
+| New project convention introduced | Add to the relevant section |
+| Copilot ignores scope control | Strengthen "Code Review Scope" section |
+| Copilot creates duplicate comments | Strengthen "Comment Behavior" section |
+
+### When NOT to Add Rules
+
+- Don't add rules for things ECS/Rector auto-fix (Copilot doesn't need to know)
+- Don't add rules that duplicate `AGENTS.md` content (Copilot doesn't read `AGENTS.md`)
+- Don't add overly specific rules for one-off situations
+
+## Relationship to Other Tools
+
+| Tool | Role | Config |
+|---|---|---|
+| **Copilot** | IDE suggestions + PR reviews | `.github/copilot-instructions.md` |
+| **Augment** | Agent workflows + deep analysis | `.augment/` + `agents/` |
+| **Greptile** | PR review bot (if enabled) | Separate config |
+| **ECS** | Code style auto-fix | `ecs.php` (project root) |
+| **Rector** | Code refactoring auto-fix | `rector.php` (project root) |
+| **PHPStan** | Static analysis | `phpstan.neon` (project root) |
+
+Copilot and Augment complement each other:
+- **Copilot** handles real-time suggestions and automated PR reviews
+- **Augment** handles complex workflows, deep analysis, and multi-step tasks
+
+## Related
+
+- **File:** `.github/copilot-instructions.md` — Copilot configuration
+- **Command:** `/fix-pr-comments` — fix all review comments (bot + human)
+- **Skill:** `code-review` — PR review process and conventions
+
+
+## Output format
+
+1. Updated copilot-instructions.md or related config file
+2. Summary of changes and which Copilot behavior is affected
+
+## Gotcha
+
+- copilot-instructions.md is for GitHub Copilot, NOT for Augment — don't mix audiences.
+- Don't duplicate .augment/ content into copilot-instructions.md — it bloats the file and → drift.
+- Copilot reads the ENTIRE instructions file on every request — keep it under 500 lines.
+
+## Do NOT
+
+- Do NOT let Copilot generate code that violates project coding standards.
+- Do NOT accept Copilot review comments without verifying them against the codebase.
+
+## Auto-trigger keywords
+
+- GitHub Copilot
+- copilot instructions
+- PR review
+- copilot behavior