@event4u/agent-config 1.9.1

package/.agent-src/commands/context-refactor.md

@@ -0,0 +1,170 @@
+---
+name: context-refactor
+skills: [agent-docs-writing]
+description: Analyze, update, and extend an existing context document
+disable-model-invocation: true
+---
+
+# context-refactor
+
+## Instructions
+
+### 1. Find the context
+
+- List all context documents in `agents/contexts/`.
+- Also check module-level `app/Modules/*/agents/contexts/`.
+
+If only one context exists, ask if that's the one to refactor.
+If the user has a context file open in their editor, use that one.
+If multiple exist, show a list:
+
+```
+📂 Existing context documents:
+
+  #  Name                    Ort                  Typ            Letzte Aktualisierung
+  ─  ──────────────────────  ───────────────────  ─────────────  ─────────────────────
+  1  client-software.md      Modul: ClientSoftware Module        2026-03-15
+  2  import-pipeline.md      Projekt-Root          Domain        2026-03-10
+  3  probaus-api.md          Projekt-Root          Integration   2026-02-28
+
+Which context do you want to update? (number or name)
+```
+
+If no contexts exist:
+```
+ℹ️  No context documents found. Create one first with /context-create.
+```
+Stop.
+
+### 2. Load and display the context
+
+- Read the selected context file completely.
+- Display a summary:
+
+```
+═══════════════════════════════════════════════
+  ✏️  CONTEXT: {title}
+═══════════════════════════════════════════════
+
+📊 Typ:              {type}
+📅 Last updated:     {last updated}
+📦 Module:           {module or "project-wide"}
+
+───────────────────────────────────────────────
+CURRENT CONTENT:
+───────────────────────────────────────────────
+
+  Key Files:       {count}
+  Key Classes:     {count}
+  DB Tables:       {count}
+  API Endpoints:   {count}
+  Known Issues:    {count}
+
+═══════════════════════════════════════════════
+```
+
+### 3. Re-analyze the code
+
+Re-analyze the documented area to find changes:
+
+- Check if documented files still exist.
+- Look for new files/classes that aren't documented.
+- Verify database tables and endpoints are still accurate.
+- Check for new tests.
+
+**Show findings:**
+
+```
+🔍 Re-analysis complete:
+
+  ✅  Still current:
+    • ImportService — unchanged
+    • 8 Models — all present
+
+  ⚠️  Outdated / changed:
+    • ProcessImportCommand — new parameters added
+    • ImportUploadType — 2 new enum values
+
+  🆕 New (not documented):
+    • ImportValidationService (newly added)
+    • api/v1/imports/validate endpoint
+
+  ❌  Removed:
+    • OldImportHelper — no longer exists
+```
+
+### 4. Ask what to do
+
+```
+What do you want to adjust?
+
+1. 🔄 Auto-update everything (based on the analysis)
+2. ✏️ Manually edit specific sections
+3. ➕ Add new areas
+4. 🗑️ Remove outdated entries
+5. 💬 Something else
+```
+
+**Option 1 — Auto-update:**
+- Remove entries for deleted files/classes.
+- Add entries for new files/classes.
+- Update changed entries.
+- Show all changes for confirmation before applying.
+
+**Option 2 — Manual edit:**
+Show section list:
+```
+Which section?
+
+1. Overview
+2. Key Files
+3. Key Classes & Services
+4. Database
+5. API Endpoints
+6. Dependencies
+7. Patterns & Conventions
+8. Known Issues / Technical Debt
+9. Notes
+```
+
+**Option 3 — Add new areas:**
+- Ask what to add.
+- Analyze the relevant code.
+- Add new sections or entries.
+
+### 5. Apply changes
+
+- Update the context file.
+- Update `Last Updated` to today's date.
+- Show a diff summary:
+
+```
+───────────────────────────────────────────────
+CHANGES:
+───────────────────────────────────────────────
+
+  🆕 Added: 3 Key Files, 1 Service, 1 Endpoint
+  ✏️ Updated: 2 Classes, 1 Known Issue
+  🗑️ Removed: 1 obsolete service
+  📅 Last Updated: 2026-03-20
+```
+
+### 6. Ask for additions
+
+```
+Anything else to add?
+
+1. ➕ Yes — document another area
+2. 🔍 Investigate a specific class/service in detail
+3. ✅ No, done
+```
+
+If option 1 or 2 → loop back to analysis and update.
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Always re-analyze the code** before updating — don't just edit text.
+- **Show changes before applying** — the user should confirm.
+- **Preserve user-written notes and context** — don't overwrite manual additions.
+- **Update `Last Updated`** after every change.

package/.agent-src/commands/copilot-agents-init.md

@@ -0,0 +1,150 @@
+---
+name: copilot-agents-init
+description: Create AGENTS.md and .github/copilot-instructions.md from scratch in the consumer project — interactive, auto-detects stack, never leaks other projects' identifiers.
+skills: [copilot-config, copilot-agents-optimization, agent-docs-writing]
+disable-model-invocation: true
+---
+
+# /copilot-agents-init
+
+Interactive initializer that **creates** `AGENTS.md` and
+`.github/copilot-instructions.md` in the consumer project from the
+package-shipped templates (`.augment/templates/AGENTS.md` and
+`.augment/templates/copilot-instructions.md`), filling in placeholders
+based on auto-detected stack + user answers.
+
+Use when either file is missing, or the user wants to start over with a
+clean scaffold. For tuning an existing file, use `/copilot-agents-optimize`.
+
+## Steps
+
+### 1. Precondition checks
+
+```bash
+ls AGENTS.md .github/copilot-instructions.md 2>/dev/null
+ls .augment/templates/AGENTS.md .augment/templates/copilot-instructions.md
+```
+
+Outcomes:
+
+| State | Action |
+|---|---|
+| Both targets missing | Proceed |
+| One exists, other missing | Ask whether to fill only the missing one |
+| Both exist | Ask confirmation — offer `/copilot-agents-optimize` instead |
+| Template missing | Abort with "package not installed" hint |
+
+### 2. Auto-detect stack
+
+Read (in this order) and record what is found:
+
+- `composer.json` → framework (Laravel / Symfony), PHP version, package name
+- `package.json` → framework (Next.js / React / Vue / Node), engines
+- `pyproject.toml` / `requirements.txt` → Python framework + version
+- `Gemfile` → Rails
+- `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle` → language/framework
+
+Secondary signals:
+
+- `Dockerfile`, `docker-compose.yml` → containerized setup
+- `Makefile`, `Taskfile.yml`, `package.json` scripts → dev commands
+- `phpunit.xml` / `pest.config` / `jest.config` / `vitest.config` / `pytest.ini` → test framework
+- `phpstan.neon`, `rector.php`, `eslint.config.js`, `ruff.toml` → quality tools
+
+Present a numbered table so the user can confirm or correct:
+
+```
+Detected:
+> 1. Language: {lang}            — correct? yes / edit
+> 2. Framework: {framework}      — correct? yes / edit
+> 3. Database: {db}              — correct? yes / skip / edit
+> 4. Test framework: {tests}     — correct? yes / edit
+> 5. Dev commands: {commands}    — correct? yes / edit
+```
+
+### 3. Gather remaining answers
+
+Ask for values that cannot be auto-detected — one question at a time,
+always with numbered options where applicable:
+
+1. **Project name** — default = `{{repo_name}}` from git remote or
+   directory name.
+2. **One-line description** — used in copilot-instructions.md.
+3. **Architecture style** — e.g. "Controllers thin, logic in services,
+   validation via FormRequests". Offer `/optimize-agents` style presets
+   based on detected framework.
+4. **User-facing strings strategy** — translation files? hardcoded?
+   default per framework.
+5. **Additional conventions** — free text, optional.
+
+### 4. Generate files
+
+Read the templates, substitute placeholders:
+
+| Placeholder | Source |
+|---|---|
+| `{{project_name}}` | Step 3.1 |
+| `{{project_description}}` | Step 3.2 |
+| `{{project_description_oneline}}` | Short version of 3.2 |
+| `{{primary_language}}`, `{{framework}}`, `{{database}}`, `{{test_framework}}`, `{{code_style_tool}}` | Step 2 |
+| `{{dev_start_command}}`, `{{dev_test_command}}` | Step 2 Makefile / scripts |
+| `{{project_structure_notes}}`, `{{testing_notes}}`, `{{quality_tools_notes}}` | Offer framework-specific defaults, let user edit |
+| `{{architecture_notes}}`, `{{coding_standards}}`, `{{framework_conventions}}` | Offer defaults + user edits |
+| `{{test_all_command}}`, `{{test_targeted_command}}`, `{{testing_extra_notes}}` | From detected test framework |
+| `{{user_facing_strings_strategy}}` | Step 3.4 |
+| `{{target_language_level}}` | e.g. "PHP 8.2 / Laravel 11" |
+
+Remove the HTML comments starting with `<!-- AGENTS.md — entry point …`
+and `<!-- copilot-instructions.md — read by GitHub Copilot …` — they are
+instructions for the human user and no longer needed once filled.
+
+Keep the **example** HTML comments (those starting with `<!-- Replace with
+your actual stack. Examples:`) — they help future maintenance.
+
+### 5. Portability verification
+
+Before writing, scan the generated content for forbidden identifiers:
+
+- Any project name from `agents/` module docs except the one chosen in 3.1
+- Any reference to vendor-specific internal tools not in the user's stack
+- Any identifier listed in `FORBIDDEN_IDENTIFIERS` in
+  `scripts/check_portability.py` (the package ships a blocklist of
+  legacy/adjacent project names that must never leak into consumer files)
+- The package's own name (e.g. the shared-config package itself), unless
+  the consumer project explicitly depends on it
+
+If any hit is found, flag it and ask for a replacement. This mirrors what
+`scripts/check_portability.py` enforces for package files.
+
+### 6. Write files
+
+Write to `AGENTS.md` and `.github/copilot-instructions.md` (create
+`.github/` if missing). Report:
+
+```
+✅  AGENTS.md written (X lines)
+✅  .github/copilot-instructions.md written (Y lines)
+
+Next steps:
+  1. Review both files and refine sections that say "document your …"
+  2. Commit them as part of the project's initial agent setup
+  3. Run `/copilot-agents-optimize` periodically to deduplicate against .augment/
+```
+
+### 7. Follow-ups
+
+If `agents/` directory does not exist, suggest running `/agents-prepare`.
+If `.agent-settings.yml` does not exist, suggest running `/config-agent-settings`.
+
+## Rules
+
+- **Never copy from the package's own root `AGENTS.md` or
+  `.github/copilot-instructions.md`.** Those are meta docs about the
+  package, not templates.
+- **Always start from `.augment/templates/`** — that is the only portable
+  source.
+- **Refuse to overwrite** existing files without explicit `--force` or
+  interactive confirmation.
+- **Never embed identifiers from other projects** — if the consumer's repo
+  is `acme/widget`, the generated file must say `acme/widget`, not any
+  name encountered while scaffolding the shared package.

package/.agent-src/commands/copilot-agents-optimize.md

@@ -0,0 +1,251 @@
+---
+name: copilot-agents-optimize
+description: Analyzes and refactors AGENTS.md and copilot-instructions.md — removes duplications, enforces line budgets, and ensures both files are optimized for their audience.
+skills: [copilot-agents-optimization, copilot-config, agent-docs-writing]
+disable-model-invocation: true
+---
+
+# /copilot-agents-optimize
+
+Analyzes and refactors `AGENTS.md` and `.github/copilot-instructions.md` against the `.augment/` ecosystem.
+
+## Steps
+
+### 1. Measure current state
+
+```bash
+wc -l AGENTS.md .github/copilot-instructions.md
+```
+
+Report line counts with budget status:
+
+| File | Lines | Budget | Status |
+|---|---|---|---|
+| `AGENTS.md` | {n} | ≤ 500 ideal, max 1000 | 🟢/🟡/🔴 |
+| `copilot-instructions.md` | {n} | ≤ 500 ideal, max 1000 | 🟢/🟡/🔴 |
+
+### 2. Scan for duplications
+
+Read both files and compare against `.augment/` content:
+
+**Check against rules:**
+```bash
+ls .augment/rules/*.md
+```
+For each rule, check if AGENTS.md or copilot-instructions.md duplicates its content.
+
+**Check against guidelines:**
+```bash
+find .augment/guidelines/ -name '*.md'
+```
+For each guideline, check if either file repeats the same conventions.
+
+**Check against skills:**
+```bash
+ls .augment/skills/*/SKILL.md
+```
+For each skill, check if either file contains domain knowledge that belongs in the skill.
+
+**Check between the two files:**
+Compare sections — anything duplicated between AGENTS.md and copilot-instructions.md
+that isn't required for Copilot's self-containment.
+
+### 2.5. Scan for legacy identifiers and stack mismatches
+
+Before deduplicating, verify the content still **applies to the current
+project**. Files drift in three ways:
+
+- **Legacy leakage** — identifiers from a former, forked, or adjacent
+  project (renamed repo, split monorepo, content copied from a sibling).
+- **Stack mismatch** — the file claims tech the project no longer uses
+  (e.g. "Laravel 11 + MariaDB" in a repo that is now a pure Python
+  library).
+- **Dead commands** — Make targets, Artisan commands, docker services
+  that no longer exist.
+
+**A. Legacy-identifier scan**
+
+Use the package's portability blocklist as the baseline:
+
+```bash
+python3 -c "import sys; sys.path.insert(0, 'scripts'); \
+  from check_portability import FORBIDDEN_IDENTIFIERS; \
+  [print(i) for i in FORBIDDEN_IDENTIFIERS]" 2>/dev/null
+```
+
+Plus any identifier from `agents/` module docs that does NOT match the
+current project name (see step 2.5.B to determine the current project).
+
+For each identifier, grep both files and report **every** hit:
+
+```bash
+for ident in "${forbidden_identifiers[@]}"; do
+  grep -n -iE "\b${ident}\b" AGENTS.md .github/copilot-instructions.md
+done
+```
+
+Every hit is a 🔴 **blocker** — these must be fixed or removed before any
+other optimization. Leaking another project's name into the consumer's
+own docs is the failure mode that made this step exist.
+
+**B. Stack-coherence scan**
+
+Auto-detect the real stack (same logic as `/copilot-agents-init` step 2):
+
+| Source file | Signal |
+|---|---|
+| `composer.json` | PHP, Laravel/Symfony, package name, PHP version |
+| `package.json` | Node, Next.js/React/Vue, engines |
+| `pyproject.toml` / `requirements.txt` | Python + framework |
+| `Gemfile` | Ruby on Rails |
+| `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle` | Language |
+| `docker-compose.yml` | Service names actually used |
+| `Makefile` / `Taskfile.yml` / `package.json` scripts | Dev commands |
+
+Compare each claim in AGENTS.md / copilot-instructions.md against the
+detected stack. Flag mismatches:
+
+| Claim in doc | Reality | Severity |
+|---|---|---|
+| "Laravel 11" | no `laravel/framework` in composer.json | 🔴 |
+| "MariaDB" | no DB driver or docker service | 🟡 |
+| service name `db` | `docker-compose.yml` has `mariadb` only | 🟡 |
+| `make start` | `Makefile` absent OR target missing | 🔴 |
+| "PHP 8.2" | `composer.json` requires `^8.1` | 🟡 |
+
+**C. Dead-command scan**
+
+Extract every invoked command from both files:
+
+```bash
+grep -oE '(make|task|composer|npm|pnpm|yarn|php artisan|python|./)[a-zA-Z0-9 _:./-]+' \
+  AGENTS.md .github/copilot-instructions.md | sort -u
+```
+
+For each hit, verify it exists:
+
+- `make X` → `grep -q "^${X}:" Makefile`
+- `task X` → `task --list-all` contains X
+- `composer X` → `composer.json` `scripts` contains X
+- `php artisan X` → `php artisan list --no-ansi` contains X (skip if no
+  container — just note "unverified")
+- `npm/pnpm/yarn X` → `package.json` `scripts` contains X
+
+Commands that no longer resolve are 🟡 stale — propose a replacement or
+removal.
+
+### 3. Present findings
+
+Show a table of issues found, **grouped by severity**. Blockers from
+step 2.5 come first:
+
+| # | File | Section | Issue | Severity | Action |
+|---|---|---|---|---|---|
+| 1 | AGENTS.md | "Quick Setup" | Mentions a forbidden identifier from the blocklist | 🔴 | Replace or remove |
+| 2 | copilot | "Tech stack" | Claims Laravel 11, project is Python | 🔴 | Full rewrite |
+| 3 | AGENTS.md | "Commands" | `make start` target not in Makefile | 🟡 | Update or remove |
+| 4 | AGENTS.md | "Coding Standards" | Duplicates `.augment/rules/php-coding.md` | 🟢 | Remove, add reference |
+| 5 | copilot | "SOLID Principles" | Duplicates `.augment/rules/architecture.md` | 🟢 | Keep (Copilot needs it) |
+| 6 | copilot | "Trailing commas" | Auto-enforced by ECS | 🟢 | Remove |
+
+Classify each issue:
+
+| Action | Meaning |
+|---|---|
+| **Replace** | Legacy identifier → swap for the correct current name |
+| **Rewrite** | Entire section no longer matches reality — rewrite from stack detection |
+| **Remove** | Content exists in `.augment/` and the file can reference it, or command is dead |
+| **Keep** | Content is needed self-contained (copilot-instructions.md) |
+| **Compress** | Content is valid but too verbose — shorten |
+| **Extract** | Move to a dedicated file in `agents/` and link |
+| **Update** | Content is outdated or references have changed |
+
+If the 🔴 blockers exceed a reasonable rewrite effort (e.g. the entire
+"Tech stack" and "Commands" sections are wrong), offer
+`/copilot-agents-init` as an alternative instead of patching in place:
+
+> ⚠️ Detected severe drift: {N} blockers, including a completely wrong
+> tech stack.
+>
+> 1. Continue optimizing (patch in place — may require large rewrites)
+> 2. Back up current files and run `/copilot-agents-init` for a clean scaffold
+> 3. Abort
+
+### 4. Ask for confirmation
+
+> Found {n} optimizations:
+> - {x} duplicates to remove (AGENTS.md)
+> - {y} sections to compress
+> - {z} sections to extract to `agents/`
+>
+> 1. Apply all changes
+> 2. Confirm each change individually
+> 3. Only optimize AGENTS.md
+> 4. Only optimize copilot-instructions.md
+
+### 5. Apply changes
+
+For each approved change:
+
+1. **Remove duplicates** — Delete the section, add a reference line if needed
+2. **Compress** — Rewrite verbose sections as concise tables/bullets
+3. **Extract** — Create file in `agents/`, move content, add link in original
+4. **Update** — Fix outdated references, paths, or descriptions
+
+After each file is modified, verify:
+- Line count is within budget
+- No broken references
+- Self-containment preserved for copilot-instructions.md
+
+### 6. Verify cross-references
+
+Check that all references in both files are valid:
+
+```bash
+# Find all markdown links in both files
+grep -oE '\[.*\]\(.*\)' AGENTS.md .github/copilot-instructions.md
+```
+
+For each link, verify the target file exists.
+
+### 7. Report results
+
+> ✅  Optimization complete:
+>
+> | File | Before | After | Δ |
+> |---|---|---|---|
+> | `AGENTS.md` | {old} lines | {new} lines | -{diff} |
+> | `copilot-instructions.md` | {old} lines | {new} lines | -{diff} |
+>
+> **Removed duplicates:** {n}
+> **Compressed sections:** {n}
+> **Extracted content:** {n} (to `agents/`)
+
+### 8. Suggest follow-ups
+
+If issues were found that need manual attention:
+
+> ⚠️ Manual review recommended:
+> - {issue description}
+
+If `.augment/` content is missing that both files reference:
+
+> 💡 Missing `.augment/` content:
+> - {missing skill/rule/guideline}
+
+## Rules
+
+- **Step 2.5 is mandatory.** Never skip the portability + stack scan —
+  that is the step that catches the "legacy identifier from another
+  project" failure mode. Duplication cleanup without this scan means the
+  command approves stale, wrong content.
+- **🔴 blockers are fixed first.** Don't deduplicate a section that is
+  about to be rewritten anyway.
+- **NEVER strip strong language** — "Do NOT", "NEVER", "MUST" are load-bearing words.
+  See the Iron Laws in `/optimize-agents` — they apply here too.
+- **NEVER remove examples** from `copilot-instructions.md` — Copilot Code Review cannot
+  read other files, so examples must be self-contained.
+- **`copilot-instructions.md` MUST remain self-contained** — it cannot reference `.augment/`
+  files because Copilot Code Review has no access to them. Only Copilot Chat can read other files.
+- **`AGENTS.md` MAY reference `.augment/`** — it is read by tools that can follow links.
+- **Ask before removing** — present findings first, apply after approval.

package/.agent-src/commands/create-pr-description.md

@@ -0,0 +1,112 @@
+---
+name: create-pr-description
+skills: [git-workflow]
+description: Generate a PR description as a copyable markdown block — used standalone or by create-pr
+disable-model-invocation: true
+---
+
+# create-pr-description
+
+## Input
+
+The user may or may not provide a PR URL or branch name.
+
+## Instructions
+
+### 1. Detect PR / Branch
+
+1. If the user provides a GitHub PR URL → use that PR to get the changed files via API.
+2. If no URL → **auto-detect:**
+   - Get current branch (`git branch --show-current`).
+   - Search for an open PR on that branch via GitHub API
+     (`GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}&state=open`).
+   - If exactly one PR found → use it (get files via `/pulls/{number}/files`).
+   - If no PR found → use `git diff origin/{default}..HEAD --stat` for the branch diff.
+3. **Never** reuse a PR number from earlier in the conversation.
+
+### 2. Gather context
+
+- **Jira ticket**: Extract ticket ID from branch name (e.g. `fix/DEV-4673-description` → `DEV-4673`).
+  - If found → fetch via Jira API (`GET /issue/{ticketId}`).
+  - If not found → ask the user for a ticket number. Proceed without if none.
+- **Diff summary**: `git diff origin/{default}..HEAD --stat` for changed files.
+- **Commit messages**: `git log origin/{default}..HEAD --format="%s"` for what was done.
+- **PR template**: **MUST** read `.github/pull_request_template.md`. This is mandatory, not optional.
+- **Read key changed files** to understand what was done — look for migrations, new classes,
+  modified services, route changes, config changes.
+- **Check roadmap/agent docs** that describe the feature intent (if they exist).
+
+### 3. Build the PR title
+
+- Format: `{TICKET-ID}: {summary}` (e.g. `DEV-4673: Fix absence working time calculation`).
+- Use the Jira ticket summary if available, otherwise derive from commits.
+- If no ticket: use the most descriptive commit message or ask the user.
+
+### 4. Build the PR body
+
+**ALWAYS** use the PR template (`.github/pull_request_template.md`). Fill in its sections:
+
+- **Jira badge**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
+- **Description**: Summarize the changes in 2-5 sentences. Explain *what* changed and *why*.
+  Use the Jira ticket description and commit messages as input.
+- **Type of change**: Check the appropriate checkbox(es) based on the changes.
+- **Checklist**: Leave as-is (the developer fills this in).
+- **Links**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
+- **Screenshots**: Leave as `...` unless the user provides screenshots.
+
+If no PR template exists, use this structure:
+
+```markdown
+## Jira
+[{TICKET-ID}]({JIRA_BASE_URL}/browse/{TICKET-ID})
+
+## Changes
+- Bullet list of what was changed and why
+
+### Migrations
+- List new/changed migrations (if any)
+
+### Tests
+- List new/changed tests (if any)
+
+## How to test
+- Steps to verify the changes
+```
+
+### 5. Present as copyable block
+
+Show the **title** and **body** separately, each in a fenced code block so the user can copy them:
+
+```
+📋 PR Title:
+```
+{title}
+```
+
+📋 PR Body:
+```markdown
+{body}
+```
+```
+
+### 6. Ask for feedback
+
+Ask with numbered options:
+
+```
+> 1. Looks good — done
+> 2. Adjust — I'll tell you what to change
+```
+
+
+### Rules
+
+- **All output in the user's language** — but the PR body itself is in **English**.
+- **Always show the result before any further action** — never create a PR directly from this command.
+- **Always use the PR template** — read `.github/pull_request_template.md` and fill its sections. NEVER invent a custom structure.
+- **Be concise** in the description — no filler text, no restating the ticket title as a sentence.
+- **Group related changes** in the description — don't list every file, list logical changes.
+- **Mark breaking changes** clearly if the diff shows API contract changes (new/removed fields,
+  changed endpoints, changed response structure).
+- **Mention file/class names** where helpful, but don't list every single file.
+- **Highlight things reviewers should pay attention to** — complex logic, edge cases, trade-offs.