@event4u/agent-config 1.9.1

package/.agent-src/skills/readme-reviewer/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: readme-reviewer
+description: "Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# readme-reviewer
+
+## When to use
+
+- Reviewing a newly created or rewritten README
+- Validating a README matches the actual repository
+- Auditing README quality across repos
+- Checking for hallucinated setup, commands, or features
+
+Do NOT use for:
+
+- Grammar or formatting proofreading only
+- Writing a README from scratch → use `readme-writing` or `readme-writing-package`
+
+## Goal
+
+Ensure README is correct (no invented content), aligned with the repo,
+useful for the audience, with a strong quickstart path.
+
+## Core principles
+
+- Evidence over assumption — verify every claim against the repo
+- Commands must exist — check `Taskfile.yml`, `Makefile`, `package.json scripts`
+- Examples must match real APIs — compare against source code
+- Quickstart quality matters more than completeness
+- A clean-looking README can still be technically wrong
+
+## Procedure
+
+### 1. Identify README type and audience
+
+Determine repo type (package, app, CLI, internal, framework) and audience
+(consumers, contributors, team). Check if structure matches type.
+
+### 2. Cross-check against repository
+
+Inspect truth-defining files:
+
+- `package.json` / `composer.json` — name, scripts, dependencies
+- `Dockerfile` / `docker-compose.yml` — runtime setup
+- `Taskfile.yml` / `Makefile` — available commands
+- CI workflows — what gets tested
+- Source entrypoints — actual public API
+- Config files, tests, existing docs
+
+Verify: install steps exist, commands work, features implemented, dependencies real.
+
+### 3. Validate installation and setup
+
+Check:
+
+- Install command correct and complete
+- Required post-install steps documented
+- No hidden setup assumptions
+- Environment/config requirements listed
+
+Flag: missing steps, incorrect steps, implied-but-unwritten steps.
+
+### 4. Validate usage examples
+
+Check:
+
+- First example minimal and realistic
+- Example matches actual API (verify against source)
+- Example doesn't rely on undocumented setup
+- Example not overly complex or abstract
+
+Flag: pseudo-code, oversized examples, API mismatches.
+
+### 5. Validate compatibility and requirements
+
+Check:
+
+- Runtime versions stated (PHP, Node, etc.)
+- Framework compatibility explicit
+- Dependencies declared
+
+Flag: missing compatibility, vague claims ("works with most versions"),
+unconfirmed broad support.
+
+### 6. Evaluate structure and clarity
+
+Check:
+
+- Strong first screen (what + why + quickstart before scroll)
+- Logical section order for repo type
+- No unnecessary sections (padded boilerplate)
+- No missing critical sections
+
+Common issues: architecture before installation, no quickstart, buried
+usage, generic template sections.
+
+### 7. Detect hallucinations
+
+Search for:
+
+- Commands not in repo
+- Features not implemented
+- Setup steps not supported by scripts/configs
+- Assumptions about environment or tools
+
+Classify each finding:
+
+- **Confirmed incorrect** — verifiably wrong
+- **Likely incorrect** — no evidence found, needs verification
+- **Unclear** — cannot confirm or deny, needs human input
+
+### 8. Check scope, size, and splitting
+
+- README not overloaded with deep technical detail
+- Complex content belongs in `/docs`, not README
+- Important onboarding info not missing due to over-compression
+
+Size checks:
+
+- **< 150 lines** — healthy
+- **150–300 lines** — expect a Table of Contents; flag if missing
+- **300–500 lines** — flag as overloaded; deep content should be in `/docs/`
+- **> 500 lines** — flag as broken entry point; hard split required
+
+Structure checks:
+
+- ToC present if > 150 lines or > 6 top-level (`##`) sections
+- Multi-platform install (> 5 variants) uses a table with deep links, not stacked blocks
+- `<details>` used only for secondary, bulky content — never for install, first example, or requirements
+- No duplication between README and `/docs/` (drifts over time)
+- Each `/docs/` file linked from README is self-contained (not just a fragment)
+
+→ See `guidelines/docs/readme-size-and-splitting.md` for full thresholds,
+splitting strategies, anti-patterns.
+
+## Output format
+
+### 1. Summary
+
+| Field | Value |
+|---|---|
+| Repo type | {type} |
+| Audience | {audience} |
+| Overall | {short assessment} |
+
+### 2. Findings
+
+| # | Severity | Section | Issue | Fix |
+|---|---|---|---|---|
+| 1 | ❌ Critical | Install | Command `X` does not exist | Replace with `Y` |
+| 2 | ⚠️ Major | Usage | Example uses deprecated API | Update to current API |
+| 3 | ℹ️ Minor | Structure | Requirements buried below usage | Move above install |
+
+Severity levels:
+
+- **❌ Critical** — breaks onboarding or factually incorrect
+- **⚠️ Major** — confusing, incomplete, or misleading
+- **ℹ️ Minor** — clarity, formatting, structure
+
+### 3. Confidence
+
+- What is confirmed correct
+- What needs human verification
+- What is unclear due to missing context
+
+## Gotcha
+
+- Model trusts the README instead of verifying against the repo
+- Model may miss subtle mismatches between examples and real APIs
+- Model focuses on wording/style instead of correctness
+- Well-formatted README with wrong commands worse than ugly but correct
+- Model accepts "looks reasonable" compatibility without checking CI matrix
+
+## Do NOT
+
+- Do NOT assume README is correct without checking the repo
+- Do NOT ignore missing or broken setup steps
+- Do NOT accept vague compatibility statements as valid
+- Do NOT focus only on wording while missing structural/correctness issues
+- Do NOT overlook mismatches between examples and actual source code
+- Do NOT soften findings — state issues clearly with severity

package/.agent-src/skills/readme-writing/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: readme-writing
+description: "Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# readme-writing
+
+## When to use
+
+- Creating a new README for an **application, CLI tool, internal tool, template, or framework**
+- Rewriting an outdated or weak README
+- Improving after major repo changes (new tooling, restructure)
+
+Do NOT use for:
+
+- **Packages/libraries** → use `readme-writing-package` instead
+- Minor typos, single-section updates, reference docs in separate files
+
+## Goal
+
+Accurate, evidence-based, scannable README for the intended audience.
+Reflects the real repository — not assumptions.
+
+## Core principles
+
+- Analyze first, write second — inspect repo before writing
+- Evidence-based — every command, step, feature must exist in repo
+- Strong quickstart over exhaustive noise — get started in 30 seconds
+- Right scope — overview in README, deep content in dedicated docs
+- Match repo type — package README ≠ app ≠ CLI tool ≠ framework
+
+## Procedure
+
+### 1. Identify README type and audience
+
+| Type | Audience | Priority |
+|---|---|---|
+| **Library/Package** | Developers consuming it | Install → Usage → API |
+| **Application** | Team / contributors | Setup → Dev workflow → Architecture |
+| **CLI tool** | End users | Install → Commands → Examples |
+| **Template/Starter** | Bootstrappers | What you get → Quickstart → Customize |
+| **Internal tool** | Team members | Purpose → Setup → Common tasks |
+| **Agent/Framework** | AI tools + maintainers | What it is → Install → Architecture → Extend |
+
+### 2. Inspect the repository
+
+Read truth-defining files:
+
+- `README.md` (existing), `package.json`, `composer.json`
+- `Dockerfile`, `docker-compose.yml`
+- `Taskfile.yml`, `Makefile`
+- CI workflows, config files, `docs/`, `agents/`
+
+Extract: purpose, install path, commands, requirements, workflows, testing, contribution flow.
+
+### 3. Choose sections
+
+Only include sections that provide value:
+
+1. **Title + one-line summary** — always
+2. **Why / what problem** — if not obvious from name
+3. **Key features** — if more than trivial
+4. **Requirements** — only if non-obvious
+5. **Installation / setup** — always
+6. **Usage / quickstart** — always (most important)
+7. **Configuration** — if applicable
+8. **Development workflow** — if accepts contributions
+9. **Testing / quality** — if tooling exists
+10. **Project structure** — if non-trivial
+11. **Contributing** — if open/team project
+12. **License** — if applicable
+
+Skip empty or near-empty sections entirely.
+
+### 4. Write evidence-based content
+
+- Only document commands that exist in the repo
+- Only describe setup steps supported by scripts/configs
+- Only claim features confirmed by code or docs
+- Unclear? Inspect more or ask — never invent
+
+Formatting: tables for comparisons, code blocks for commands (copy-pasteable),
+short paragraphs (max 3 sentences), directory trees for structure.
+
+### 5. Optimize for first screen
+
+Reader must answer within 10 seconds: What is this? Why? How to start?
+
+First screen (before scroll): title, summary, install or quickstart.
+
+### 6. Size and structure
+
+Keep README scannable. Past ~150 lines: add Table of Contents. Past ~300
+lines: split deep content to `/docs/` or `references/`. Use `<details>`
+only for secondary, bulky content — never for install, first example, or
+requirements.
+
+→ See `guidelines/docs/readme-size-and-splitting.md` for thresholds,
+splitting strategies (reference-split, deep-link tables, collapsibles),
+multi-audience handling, anti-patterns.
+
+### 7. Validate
+
+- [ ] Every command exists in repo (`Taskfile.yml`, `Makefile`, `package.json`, etc.)
+- [ ] Setup steps are reproducible
+- [ ] No invented features or capabilities
+- [ ] First screen answers: what, why, how-to-start
+- [ ] No dead sections (heading with 1-2 trivial sentences)
+- [ ] Deep content in dedicated docs, not crammed in README
+- [ ] Size below "overloaded" threshold, or splitting in place (see size guideline)
+- [ ] ToC present if > 150 lines or > 6 top-level sections
+- [ ] All file paths and references are valid
+
+## Output format
+
+1. Full README draft
+2. Short note: detected repo type + audience
+3. Uncertainties or assumptions needing confirmation
+
+## Gotcha
+
+- Model writes generic boilerplate instead of repo-specific docs
+- Model includes commands/steps that don't exist in the repo
+- Model over-documents, burying the quickstart under walls of text
+- Existing README structure can mislead — don't preserve weak structure blindly
+- Package READMEs need install/usage focus, not internal dev workflow
+- Model forgets to validate commands against `Taskfile.yml` / `Makefile` / `package.json`
+
+## Do NOT
+
+- Do NOT invent features, setup steps, or commands not in the repo
+- Do NOT copy generic templates without adapting to the project
+- Do NOT overload with deep reference material — link to docs
+- Do NOT write for "everyone" — choose a real audience
+- Do NOT skip repository inspection before writing
+- Do NOT preserve weak structure just because it exists
+- Do NOT add marketing language ("blazing fast", "revolutionary")

package/.agent-src/skills/readme-writing-package/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: readme-writing-package
+description: "Use when creating or rewriting a README for a reusable package or library. Focus on installability, minimal usage example, compatibility, and developer onboarding."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# readme-writing-package
+
+## When to use
+
+- Creating a README for a package, library, SDK, or framework extension
+- Rewriting after major changes (new API, version bump, new registry)
+- Improving a weak package README (missing install, no example, no compatibility)
+- Documenting for Packagist, npm, or internal registries
+
+Do NOT use for:
+
+- Full applications, CLI tools, internal team repos → use `readme-writing`
+- Minor typos, single-section updates, deep reference docs in `/docs`
+
+## Goal
+
+Package README that makes adoption easy. Developer knows within 30 seconds:
+what it does, whether it fits their stack, how to install, how to use.
+
+## Core principles
+
+- User adoption over internal architecture — consumer first, maintainer second
+- Install + first example = most important sections
+- Compatibility must be explicit — don't imply broad support without evidence
+- First example: real, minimal, verified — no pseudo-code
+- README = onboarding, /docs = reference
+
+## Procedure
+
+### 1. Identify package type and audience
+
+| Type | Audience | README focus |
+|---|---|---|
+| **Library** | Any developer | Install → Usage → API surface |
+| **Framework extension** | Framework users | Requirements → Install → Register → Use |
+| **Plugin** | Plugin host users | Compatibility → Install → Config → Use |
+| **SDK** | API consumers | Auth → Install → First request → Response handling |
+| **Internal shared package** | Team members | Purpose → Install → Integration → Dev workflow |
+
+### 2. Inspect package truth sources
+
+- `composer.json` / `package.json` — name, description, requirements, scripts
+- Source entrypoints — public API, main classes/functions
+- Config files — publishable configs, defaults
+- CI workflows — supported versions matrix
+- Tests — actual API usage patterns
+- `CHANGELOG.md` / releases — current state, breaking changes
+- Examples directory if present
+
+Extract: name, purpose, install command, runtime requirements, supported
+versions, public API, setup steps, test/lint commands.
+
+### 3. Choose sections
+
+Priority order for packages:
+
+1. **Title + one-line summary** — always
+2. **Why / what problem** — if not obvious from name
+3. **Requirements / compatibility** — always (versions, extensions, frameworks)
+4. **Installation** — always (exact command, post-install steps)
+5. **Minimal usage example** — always (most important)
+6. **Configuration** — if config publish, env vars, or registration needed
+7. **More examples** — if API has multiple entry points
+8. **Development / testing** — for maintainers/contributors
+9. **Contributing** — if open/team project
+10. **License** — if applicable
+
+Skip sections with no real content. Never pad.
+
+### 4. Write requirements and compatibility
+
+State only what is tested and supported:
+
+```
+## Requirements
+
+- PHP ^8.2
+- Laravel 11.x
+- ext-json
+```
+
+Don't imply broad compatibility if only tested in narrow range. Include
+framework version, language version, required extensions, services.
+
+### 5. Write installation that actually works
+
+Exact install command and required follow-up:
+
+```bash
+composer require vendor/package
+
+# If framework integration needed:
+php artisan vendor:publish --tag=package-config
+```
+
+Validate each step against the codebase. Include post-install steps
+(publish, register, env setup) if required.
+
+### 6. Write minimal working example
+
+**Most critical section.** Rules:
+
+- Smallest possible working example — one use case, one result
+- Real API calls, not pseudo-code
+- Copy-pasteable without hidden setup
+- Show expected result or effect if helpful
+- Must match actual package API (verify against source)
+
+Bad: abstract, large, requires unexplained setup.
+Good: 5-15 lines, directly relevant, immediately runnable.
+
+### 7. Keep architecture out of README — use reference-split
+
+Move deep content to dedicated docs. Recommended layout:
+
+```
+README.md              ← entry: what, why, install, minimal usage
+docs/
+  installation.md      ← full install matrix, post-install steps
+  usage.md             ← extended examples, common patterns
+  architecture.md      ← internal design, decisions
+  api.md               ← full API reference
+  migration.md         ← version upgrade guides
+```
+
+Multi-platform install (> 5 variants): prefer single table with deep
+links over stacked inline blocks. Occasionally-needed detail (long
+platform quirks, troubleshooting): use `<details>` — never for install,
+first example, or requirements.
+
+→ See `guidelines/docs/readme-size-and-splitting.md` for thresholds,
+deep-link-table pattern, collapsibles, anti-patterns (premature
+splitting, duplication between README and `/docs/`).
+
+README = enough to adopt. Docs = enough to master.
+
+### 8. Validate
+
+- [ ] Install command is correct and complete
+- [ ] Compatibility/requirements match `composer.json` / `package.json` / CI matrix
+- [ ] First example matches real API (verified against source)
+- [ ] All documented commands exist in repo
+- [ ] No invented features or capabilities
+- [ ] Consumer can get started without reading source code
+- [ ] Deep content in docs, not README (see size guideline)
+- [ ] Multi-platform install uses a table, not stacked blocks
+- [ ] No duplication between README and `/docs/`
+- [ ] First screen shows: what, install, requirements
+
+## Output format
+
+1. Full README draft
+2. Detected package type + audience
+3. Compatibility summary
+4. Uncertainties needing confirmation
+5. Suggested follow-up docs if README would become too large
+
+## Gotcha
+
+- Model writes package READMEs like app READMEs (too much architecture)
+- Model invents compatibility claims or setup steps
+- First example often too large, too abstract, or uses pseudo-code
+- Model over-explains internals before showing how to use the package
+- Existing README may be outdated — verify against `composer.json` / source
+- Model forgets post-install steps (config publish, service provider, env vars)
+
+## Do NOT
+
+- Do NOT invent package capabilities or compatibility
+- Do NOT skip the minimal working example
+- Do NOT prioritize internal architecture over user onboarding
+- Do NOT document commands not in the repo
+- Do NOT hide requirements or version constraints
+- Do NOT write a giant example when 10 lines would do
+- Do NOT overload README with reference material — link to /docs

package/.agent-src/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: receiving-code-review
+description: "Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'."
+personas:
+  - critical-challenger
+source: package
+---
+
+# receiving-code-review
+
+## When to use
+
+* PR has review comments (bots like Copilot, Greptile, Augment, or human
+  reviewers) and the next step is addressing them
+* Someone pasted review feedback and asks you to "fix it" or "handle it"
+* A pair-programming partner gave verbal suggestions about code you
+  just wrote
+* You are tempted to reply "you are absolutely right" before reading
+  the rest of the comment
+
+Do NOT use when:
+
+* You are writing a review yourself (different discipline)
+* User explicitly asks for blind implementation of a specific change
+  not framed as review feedback
+* Pure style/formatting the linter should decide automatically — run
+  the linter
+
+## Goal
+
+Treat review feedback as **suggestions to evaluate**, not orders to
+execute. Separate correct feedback from reviewer confusion. Push back
+with technical reasoning when the suggestion is wrong for this
+codebase. Never agree performatively.
+
+## The Iron Law
+
+```
+NO IMPLEMENTATION UNTIL THE FEEDBACK IS UNDERSTOOD AND VERIFIED.
+```
+
+A "fix" implemented against a misread comment is worse than no fix —
+ships the wrong behavior under the label of "addressed feedback".
+
+## Procedure
+
+### 1. Read the full comment set before touching code
+
+Read **every** open comment on the PR first. Comments often relate to
+each other — fixing comment #3 in isolation can conflict with #5. Group:
+
+* **Blocking** — breaks behavior, introduces a bug, security issue
+* **Important** — logic correct but design / readability issue
+* **Minor** — naming, comment style, formatting the linter missed
+* **Wrong** — reviewer misunderstood the code, or suggestion regresses
+  another behavior
+
+### 2. Restate each comment in your own words
+
+For every comment, write (internally or to the user): *"The reviewer
+is asking me to X because Y."*
+
+Cannot complete that sentence confidently → the comment is unclear. Ask
+for clarification **before** implementing anything. Do not implement
+the clear ones first and ask later — they may be linked.
+
+### 3. Verify each claim against the code
+
+For each blocking/important comment:
+
+* Reproduce the alleged issue locally (run the test, hit the endpoint,
+  read the actual runtime value — see [`systematic-debugging`](../systematic-debugging/SKILL.md))
+* Check what the code actually does, not what the reviewer **thinks**
+  it does
+* Check whether the suggested fix would break another test or caller
+* Check `git blame` / history — current code may be that way for a reason
+* **Consult memory for prior context.** Via
+  [`memory-access`](../../guidelines/agent-infra/memory-access.md),
+  call `retrieve(types=["historical-patterns", "architecture-decisions"],
+  keys=<files in the review>, limit=3)`. A registered historical pattern
+  may confirm the reviewer's concern (accept) or an architecture
+  decision may explain why the current shape is intentional (push back
+  with the cited `id`).
+
+### 4. Decide: accept, push back, or escalate
+
+| Situation | Response |
+|---|---|
+| Reviewer right, fix local, no caller impact | Implement, reference the comment in the commit message |
+| Reviewer right but fix affects other callers | Note downstream effects in the reply, then implement |
+| Reviewer wrong — misreading the code | Reply with evidence (specific line / test / value), do not change code |
+| Reviewer suggests a feature the codebase does not use (YAGNI) | Reply asking whether the feature is actually needed, do not build speculatively |
+| Reviewer and user / architecture disagree | Escalate to the user before implementing either path |
+
+### 5. Reply in the right place, with the right tone
+
+* Inline PR comments → reply **in the thread** of that comment, not as
+  a top-level PR comment
+* Quote **evidence**, not opinion — "line 47 already handles this via
+  `$x->isNull()`" beats "I think that's fine"
+* No flattery. No "great catch", "absolutely right", "thanks for
+  noticing". The `language-and-tone` rule already bans this — actions
+  are the acknowledgement
+* If you were wrong in your earlier pushback, state it factually and
+  move on. No long apology
+
+### 6. Implement in priority order, one at a time
+
+1. Blocking issues first
+2. Important issues next
+3. Minor issues last (or bundle into a single commit)
+4. Wrong / YAGNI: no code change, only a reply with reasoning
+
+Run relevant tests and linters **between** each group — do not batch
+four changes and then run tests once. See
+[`verify-before-complete`](../verify-before-complete/SKILL.md).
+
+## Output format
+
+When reporting back to the user after handling review:
+
+1. **Triage table** — comment → classification → decision
+2. **Implemented changes** — bullet per change with file + commit ref
+3. **Pushed back** — bullet per rejected comment with the evidence
+4. **Outstanding** — anything awaiting clarification, with the specific
+   question
+
+## Gotchas
+
+* Bot comments (Copilot, Greptile) are **not** automatically right.
+  Frequently flag false positives on patterns the codebase uses
+  deliberately. Verify like a human comment.
+* A comment reading like a question ("should this be X?") is often a
+  polite way of saying "change it to X". Ask if unclear.
+* Resolving a comment in the GitHub UI without an accompanying fix or
+  reply silently marks it handled — reviewers may miss the lack of
+  substance.
+* Stacked PRs — a comment on the base PR may already be fixed in the
+  child PR. Check both before touching code.
+* A suggestion that passes review aesthetics but fails the test suite
+  is still a regression. Run tests even when "the change is trivial".
+* Flattery leaks in as "good point" or "thanks". Delete before sending.
+
+## Do NOT
+
+* Do NOT reply "you are absolutely right", "great catch", or any
+  flattery variant — actions acknowledge, words do not
+* Do NOT implement a suggestion before verifying it against the code
+* Do NOT fix the clear items first and ask about the unclear ones later
+  when the items are linked
+* Do NOT accept a reviewer's suggestion that conflicts with an explicit
+  architectural decision without raising it
+* Do NOT batch multiple unrelated fixes into one commit — reviewers
+  cannot re-review selectively
+* Do NOT mark a comment resolved without either a code change or a
+  reply with reasoning
+
+## Anti-patterns
+
+* Replying "Fixed!" after a commit that does not actually address the
+  comment (wrong file, missed case)
+* Rewriting the comment author's suggestion into your own words without
+  checking whether the reinterpretation still matches intent
+* Implementing the YAGNI-suggested feature "just in case" the reviewer
+  comes back
+* Silent disagreement — ignoring a comment without a reply
+
+## When to hand over to another skill / command
+
+* Executing fixes across many comments → [`fix-pr-comments`](../../commands/fix-pr-comments.md)
+  (handles both bot + developer), [`fix-pr-bot-comments`](../../commands/fix-pr-bot-comments.md),
+  [`fix-pr-developer-comments`](../../commands/fix-pr-developer-comments.md)
+* Running the full verification gate before pushing replies →
+  [`verify-before-complete`](../verify-before-complete/SKILL.md)
+* Writing the commit message that references the review →
+  [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md)
+* Digging into *why* the reviewer's scenario actually fails →
+  [`systematic-debugging`](../systematic-debugging/SKILL.md)
+
+## Validation checklist
+
+Before considering review handling done:
+
+* [ ] Every open comment read, classified, decision made
+* [ ] No comment implemented without a one-sentence restatement
+* [ ] Every implemented fix verified by a test or runtime check
+* [ ] Every rejected comment has a reply quoting evidence
+* [ ] No comment marked resolved without code change or reply
+* [ ] No reply contains flattery
+* [ ] Linters and relevant tests pass after the changes