@event4u/agent-config 1.16.0 → 1.17.0

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

@@ -17,15 +17,15 @@ execution:
 - Auditing README quality across repos
 - Checking for hallucinated setup, commands, or features
 
-Do NOT use for:
+Do NOT use when:
 
-- Grammar or formatting proofreading only
+- Only proofreading grammar or formatting
 - 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.
+Ensure the README is correct (no invented content), aligned with the repo,
+useful for the intended audience, and has a strong quickstart path.
 
 ## Core principles
 
@@ -39,8 +39,8 @@ useful for the audience, with a strong quickstart path.
 
 ### 1. Identify README type and audience
 
-Determine repo type (package, app, CLI, internal, framework) and audience
-(consumers, contributors, team). Check if structure matches type.
+Determine repo type (package, app, CLI, internal, framework) and target audience
+(consumers, contributors, team). Check if README structure matches this type.
 
 ### 2. Cross-check against repository
 
@@ -53,16 +53,17 @@ Inspect truth-defining files:
 - Source entrypoints — actual public API
 - Config files, tests, existing docs
 
-Verify: install steps exist, commands work, features implemented, dependencies real.
+Verify: install steps exist, commands work, features are implemented,
+dependencies are real.
 
 ### 3. Validate installation and setup
 
 Check:
 
-- Install command correct and complete
-- Required post-install steps documented
+- Install command is correct and complete
+- Required post-install steps are documented
 - No hidden setup assumptions
-- Environment/config requirements listed
+- Environment/config requirements are listed
 
 Flag: missing steps, incorrect steps, implied-but-unwritten steps.
 
@@ -70,10 +71,10 @@ Flag: missing steps, incorrect steps, implied-but-unwritten steps.
 
 Check:
 
-- First example minimal and realistic
+- First example is minimal and realistic
 - Example matches actual API (verify against source)
-- Example doesn't rely on undocumented setup
-- Example not overly complex or abstract
+- Example does not rely on undocumented setup
+- Example is not overly complex or abstract
 
 Flag: pseudo-code, oversized examples, API mismatches.
 
@@ -82,8 +83,8 @@ Flag: pseudo-code, oversized examples, API mismatches.
 Check:
 
 - Runtime versions stated (PHP, Node, etc.)
-- Framework compatibility explicit
-- Dependencies declared
+- Framework compatibility is explicit
+- Dependencies are declared
 
 Flag: missing compatibility, vague claims ("works with most versions"),
 unconfirmed broad support.
@@ -92,19 +93,19 @@ unconfirmed broad support.
 
 Check:
 
-- Strong first screen (what + why + quickstart before scroll)
+- Strong first screen (what + why + quickstart visible before scrolling)
 - 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.
+Common issues: architecture before installation, no quickstart,
+buried usage instructions, generic template sections.
 
 ### 7. Detect hallucinations
 
-Search for:
+Explicitly search for:
 
-- Commands not in repo
+- Commands not present in repo
 - Features not implemented
 - Setup steps not supported by scripts/configs
 - Assumptions about environment or tools
@@ -133,11 +134,11 @@ 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)
+- No duplication between README and `/docs/` (same content in two places drifts)
 - Each `/docs/` file linked from README is self-contained (not just a fragment)
 
 → See `docs/guidelines/docs/readme-size-and-splitting.md` for full thresholds,
-splitting strategies, anti-patterns.
+splitting strategies, and anti-patterns.
 
 ## Output format
 
@@ -159,9 +160,9 @@ splitting strategies, anti-patterns.
 
 Severity levels:
 
-- **❌ Critical** — breaks onboarding or factually incorrect
+- **❌ Critical** — breaks onboarding or is factually incorrect
 - **⚠️ Major** — confusing, incomplete, or misleading
-- **ℹ️ Minor** — clarity, formatting, structure
+- **ℹ️ Minor** — clarity improvement, formatting, structure
 
 ### 3. Confidence
 
@@ -171,11 +172,11 @@ Severity levels:
 
 ## Gotcha
 
-- Model trusts the README instead of verifying against the repo
+- Model tends to trust 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
+- Model may focus on wording/style instead of correctness
+- A well-formatted README with wrong commands is worse than ugly but correct
+- Model may accept "looks reasonable" compatibility without checking CI matrix
 
 ## Do NOT
 
@@ -184,4 +185,4 @@ Severity levels:
 - 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
+- Do NOT soften findings — state issues clearly with severity

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

@@ -15,29 +15,34 @@ execution:
 - 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)
+- Adapting README for a different audience
 
-Do NOT use for:
+Do NOT use when:
 
-- **Packages/libraries** → use `readme-writing-package` instead
-- Minor typos, single-section updates, reference docs in separate files
+- Writing a README for a **reusable package or library** → use `readme-writing-package` instead
+- Fixing minor typos or updating a single section
+- Writing reference docs that belong in separate files
+- Only adding a badge or version bump
 
 ## Goal
 
-Accurate, evidence-based, scannable README for the intended audience.
-Reflects the real repository — not assumptions.
+Write a README that is accurate, evidence-based, scannable, and useful 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
+- **Analyze first, write second** — inspect the repo before writing a single line
+- **Evidence-based only** — every command, setup step, and feature must exist in the repo
+- **Strong quickstart over exhaustive noise** — a reader should get started in 30 seconds
+- **Right scope** — high-level overview in README, deep content in dedicated docs
+- **Match the repo type** — a package README differs from an app, CLI tool, or framework
 
 ## Procedure
 
 ### 1. Identify README type and audience
 
+Determine repository type:
+
 | Type | Audience | Priority |
 |---|---|---|
 | **Library/Package** | Developers consuming it | Install → Usage → API |
@@ -49,94 +54,114 @@ Reflects the real repository — not assumptions.
 
 ### 2. Inspect the repository
 
-Read truth-defining files:
+Read these files to extract truth:
 
-- `README.md` (existing), `package.json`, `composer.json`
-- `Dockerfile`, `docker-compose.yml`
-- `Taskfile.yml`, `Makefile`
-- CI workflows, config files, `docs/`, `agents/`
+- `README.md` (existing, if any)
+- `package.json`, `composer.json` — name, description, scripts, dependencies
+- `Dockerfile`, `docker-compose.yml` — runtime setup
+- `Taskfile.yml`, `Makefile` — available commands
+- CI workflows — what gets tested, how
+- `docs/`, `agents/` — existing documentation
+- Config files — what tools are used
 
-Extract: purpose, install path, commands, requirements, workflows, testing, contribution flow.
+Extract: project purpose, install path, main commands, requirements,
+key workflows, testing/linting commands, contribution flow.
 
 ### 3. Choose sections
 
-Only include sections that provide value:
+Only include sections that provide value. Candidates:
 
 1. **Title + one-line summary** — always
-2. **Why / what problem** — if not obvious from name
-3. **Key features** — if more than trivial
+2. **Why / what problem it solves** — if not obvious from name
+3. **Key features or capabilities** — if more than a trivial tool
 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
+6. **Usage / quickstart** — always (most important section)
+7. **Configuration / customization** — if applicable
+8. **Development workflow** — if repo accepts contributions
 9. **Testing / quality** — if tooling exists
 10. **Project structure** — if non-trivial
-11. **Contributing** — if open/team project
+11. **Contributing** — if open or team project
 12. **License** — if applicable
 
+Do NOT include sections "because READMEs usually have them."
 Skip empty or near-empty sections entirely.
 
 ### 4. Write evidence-based content
 
-- Only document commands that exist in the repo
+Rules:
+
+- Only document commands that actually 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
+- If something is unclear: inspect more or ask — never invent
+
+Formatting:
 
-Formatting: tables for comparisons, code blocks for commands (copy-pasteable),
-short paragraphs (max 3 sentences), directory trees for structure.
+- Tables for structured comparisons (tools, options, features)
+- Code blocks for every command (copy-pasteable)
+- Short paragraphs — max 3 sentences before a break
+- Directory trees for project structure (use `tree` format)
+- Badges only if they link to live CI/release status
 
-### 5. Optimize for first screen
+### 5. Optimize for the first screen
 
-Reader must answer within 10 seconds: What is this? Why? How to start?
+A reader scanning the README should answer within 10 seconds:
 
-First screen (before scroll): title, summary, install or quickstart.
+1. What is this?
+2. Why does it exist?
+3. How do I install/start it?
+
+The first screen (before scrolling) must contain the title, summary,
+and either install command or quickstart. Everything else comes after.
 
 ### 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.
+Keep the README scannable. If it grows past ~150 lines, add a Table of
+Contents; past ~300 lines, split deep content out to `/docs/` or
+`references/`. Use `<details>` only for secondary, bulky content (never
+for install, first example, or requirements).
 
 → See `docs/guidelines/docs/readme-size-and-splitting.md` for thresholds,
 splitting strategies (reference-split, deep-link tables, collapsibles),
-multi-audience handling, anti-patterns.
+multi-audience handling, and anti-patterns.
 
 ### 7. Validate
 
-- [ ] Every command exists in repo (`Taskfile.yml`, `Makefile`, `package.json`, etc.)
-- [ ] Setup steps are reproducible
-- [ ] No invented features or capabilities
+After writing, verify:
+
+- [ ] Every documented command exists in the repo (`Taskfile.yml`, `Makefile`, `package.json scripts`, etc.)
+- [ ] Setup steps are reproducible (no missing prerequisites)
+- [ ] No features or capabilities are invented
 - [ ] 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
+- [ ] Scope is right — deep content moved to dedicated docs, not crammed in
+- [ ] Size below the "overloaded" threshold, or splitting is in place (see size guideline)
+- [ ] ToC present if README > 150 lines or > 6 top-level sections
+- [ ] Matches existing tonality if repo has established voice
 - [ ] 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
+3. Any uncertainties or assumptions that need 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`
+- The model tends to write generic boilerplate instead of repo-specific documentation
+- The model tends to include commands or setup steps that don't actually exist in the repo
+- The model tends to over-document and bury the quickstart under walls of text
+- Existing README structure can be misleading — don't preserve weak structure blindly
+- READMEs for packages consumed by others need install/usage focus, not internal dev workflow
+- The model forgets to validate commands against `Taskfile.yml` / `Makefile` / `package.json scripts`
 
 ## 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 invent features, setup steps, or commands not found in the repo
+- Do NOT copy generic README templates without adapting to the actual project
+- Do NOT overload with deep reference material — link to docs instead
 - 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")
+- Do NOT preserve weak structure from an existing README just because it exists
+- Do NOT add marketing language ("blazing fast", "revolutionary", "next-gen")

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

@@ -13,27 +13,28 @@ execution:
 ## 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
+- Rewriting a package README after major changes (new API, version bump, new registry)
+- Improving a weak package README (missing install, no example, no compatibility info)
+- Documenting a package for Packagist, npm, or internal registries
 
-Do NOT use for:
+Do NOT use when:
 
-- Full applications, CLI tools, internal team repos → use `readme-writing`
-- Minor typos, single-section updates, deep reference docs in `/docs`
+- Documenting a full application, CLI tool, or internal team repo → use `readme-writing` instead
+- Only fixing minor typos or updating a single section
+- Writing deep reference docs that belong 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.
+Package README that makes adoption easy. A developer should know within 30 seconds:
+what it does, whether it fits their stack, how to install it, and how to use it.
 
 ## 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
+- **User adoption over internal architecture** — consumer first, maintainer second
+- **Install + first example = most important sections** — everything else is secondary
+- **Compatibility must be explicit** — don't imply broad support without evidence
+- **First code example must be real, minimal, and verified** — no pseudo-code
+- **README = onboarding, /docs = reference** — keep README focused
 
 ## Procedure
 
@@ -49,16 +50,18 @@ what it does, whether it fits their stack, how to install, how to use.
 
 ### 2. Inspect package truth sources
 
+Read files that define actual package behavior:
+
 - `composer.json` / `package.json` — name, description, requirements, scripts
-- Source entrypoints — public API, main classes/functions
+- Source entrypoints — public API surface, main classes/functions
 - Config files — publishable configs, defaults
-- CI workflows — supported versions matrix
-- Tests — actual API usage patterns
+- CI workflows — what gets tested, supported versions matrix
+- Tests — reveal actual API usage patterns
 - `CHANGELOG.md` / releases — current state, breaking changes
-- Examples directory if present
+- Examples directory — if present
 
-Extract: name, purpose, install command, runtime requirements, supported
-versions, public API, setup steps, test/lint commands.
+Extract: package name, purpose, install command, runtime requirements,
+supported versions, public API, setup steps, test/lint commands.
 
 ### 3. Choose sections
 
@@ -68,14 +71,14 @@ Priority order for packages:
 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
+5. **Minimal usage example** — always (most important section)
+6. **Configuration / setup** — if config publish, env vars, or registration needed
+7. **More examples / common use cases** — if API has multiple entry points
 8. **Development / testing** — for maintainers/contributors
-9. **Contributing** — if open/team project
+9. **Contributing** — if open or team project
 10. **License** — if applicable
 
-Skip sections with no real content. Never pad.
+Skip sections that have no real content. Never pad.
 
 ### 4. Write requirements and compatibility
 
@@ -89,12 +92,12 @@ State only what is tested and supported:
 - ext-json
 ```
 
-Don't imply broad compatibility if only tested in narrow range. Include
-framework version, language version, required extensions, services.
+Do NOT 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:
+Document the exact install command and any required follow-up:
 
 ```bash
 composer require vendor/package
@@ -103,25 +106,25 @@ composer require vendor/package
 php artisan vendor:publish --tag=package-config
 ```
 
-Validate each step against the codebase. Include post-install steps
-(publish, register, env setup) if required.
+Validate each step against the actual codebase.
+Include post-install steps (publish, register, env setup) if required.
 
-### 6. Write minimal working example
+### 6. Write the minimal working example
 
-**Most critical section.** Rules:
+**This is the 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)
+- Must match the 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:
+Move deep content to dedicated docs. Recommended layout for packages:
 
 ```
 README.md              ← entry: what, why, install, minimal usage
@@ -133,13 +136,13 @@ docs/
   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.
+For multi-platform install (> 5 variants), prefer a single table with
+deep links over stacked inline blocks. For occasionally-needed detail
+(long platform quirks, troubleshooting), use `<details>` — never for
+install, first example, or requirements.
 
 → See `docs/guidelines/docs/readme-size-and-splitting.md` for thresholds,
-deep-link-table pattern, collapsibles, anti-patterns (premature
+deep-link-table pattern, collapsibles, and anti-patterns (premature
 splitting, duplication between README and `/docs/`).
 
 README = enough to adopt. Docs = enough to master.
@@ -148,11 +151,11 @@ README = enough to adopt. Docs = enough to master.
 
 - [ ] Install command is correct and complete
 - [ ] Compatibility/requirements match `composer.json` / `package.json` / CI matrix
-- [ ] First example matches real API (verified against source)
+- [ ] First example matches real API (verified against source code)
 - [ ] 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)
+- [ ] Deep content is 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
@@ -167,11 +170,11 @@ README = enough to adopt. Docs = enough to master.
 
 ## 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 writes package READMEs like app READMEs (too much architecture, not enough install/usage)
+- Model tends to invent compatibility claims or setup steps
+- First example is 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
+- Existing README may be outdated — verify against actual `composer.json` / source, not old text
 - Model forgets post-install steps (config publish, service provider, env vars)
 
 ## Do NOT
@@ -179,7 +182,7 @@ README = enough to adopt. Docs = enough to master.
 - 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 document commands not present 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
+- Do NOT write a giant example when a 10-line one would do
+- Do NOT overload README with reference material — link to /docs