@event4u/agent-config 5.10.1 → 6.0.0

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

@@ -0,0 +1,240 @@
+---
+model_tier: medium
+name: readme-writing
+description: "Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# 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)
+- Adapting README for a different audience
+
+Do NOT use when:
+
+- 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
+
+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 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
+- **Re-analyze every time** — never trust cached knowledge of the repo; the README that drifted yesterday is the README the model wrote from memory
+- **Preserve existing visual identity** — banner, badges, profile/role grids, official logo lockups stay byte-identical unless the user explicitly asks to change them
+
+## Procedure
+
+### 0. Re-analysis gate — MANDATORY before any writing
+
+Before drafting a single line, run a fresh repository inspection in **this**
+session. Do not rely on prior knowledge, prior turns, or the existing README
+prose. Produce an explicit evidence ledger:
+
+```
+ledger:
+  package:      <name + version from manifest>
+  description:  <verbatim from manifest>
+  cli_entry:    <bin / entry from manifest, if any>
+  commands:     <list of real commands from Taskfile / Makefile / package.json scripts>
+  install:      <verified install path(s) from scripts/install.* or docs>
+  doc_targets:  <list of /docs files actually linked from the new draft>
+  counts:       <skills / rules / commands / personas / advisors — if surfaced as badges>
+  visual_keep:  <line range of existing README header, banner, badge block to preserve>
+```
+
+If any cell is unknown, run `ls`, `grep`, `find`, or read the file before
+writing — never invent. If the user asks to "use the existing banner",
+locate the exact source lines and reproduce them byte-for-byte, including
+the surrounding HTML.
+
+### 1. Identify README type and audience
+
+Determine repository type:
+
+| 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 these files to extract truth:
+
+- `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: project purpose, install path, main commands, requirements,
+key workflows, testing/linting commands, contribution flow.
+
+### 3. Choose sections
+
+Only include sections that provide value. Candidates:
+
+1. **Title + one-line summary** — always
+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 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 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
+
+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
+- If something is unclear: inspect more or ask — never invent
+
+Formatting:
+
+- 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 the first screen
+
+A reader scanning the README should answer within 10 seconds:
+
+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 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, and anti-patterns.
+
+### 7. Validate links and detect orphans — MANDATORY
+
+For every internal link in the new draft:
+
+1. Resolve the path. If it points to a file, `test -f` the path. If a
+   directory, `test -d`. Strip `#anchor` and `?query` before the check.
+2. For every anchor link (`file.md#section`), grep the target file for
+   the heading slug. Missing anchor = broken link.
+3. Build the **link-delta** between the old README and the new one:
+   - **kept**: linked in both
+   - **added**: only linked by the new README
+   - **dropped**: only linked by the old README
+
+For every `dropped` target, search the rest of the repository
+(`grep -r "<path>"` over `AGENTS.md`, `docs/`, `dist/agent-src*/`,
+`.augment/`, `packages/`). If no other file references it, mark
+**orphan-candidate**. Surface the list to the user — do not delete
+silently.
+
+### 8. Validate
+
+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 contract** — within the first ~40 lines: project name, one-sentence pitch, install command (or pointer), and the primary CTA
+- [ ] Banner, badges, and any explicit "preserve" block from Step 0 are byte-identical to source
+- [ ] No dead sections (heading with 1-2 trivial sentences)
+- [ ] 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
+- [ ] Every internal link resolved per Step 7 — zero broken file or anchor links
+- [ ] Orphan-candidate list produced even if empty
+
+## Output format
+
+1. Full README draft
+2. Short note: detected repo type + audience
+3. **Link delta** — `kept` / `added` / `dropped` with orphan-candidates flagged
+4. Evidence ledger (Step 0) so the user can audit assumptions
+5. Any uncertainties or assumptions that need confirmation
+
+## Gotcha
+
+- 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`
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every README you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the README opens with one
+  sentence stating what the project is.
+- Per the cite-don't-restate principle, "Installation" links to the
+  canonical install script, not its full contents.
+- Per the cheap-question check, "Quick start vs. full guide" is
+  offered only when the two paths produce different artifacts.
+
+**Pre-save self-check:**
+1. Does the opening paragraph carry marketing adjectives ("modern",
+   "comprehensive", "powerful")?
+2. Are setup steps narrated instead of bulleted commands?
+3. Are screenshots / GIFs present without explicit user request?
+4. Is content duplicated from `AGENTS.md` rather than linked?
+
+## Do NOT
+
+- 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 from an existing README just because it exists
+- Do NOT add marketing language ("blazing fast", "revolutionary", "next-gen")

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

@@ -0,0 +1,350 @@
+---
+model_tier: medium
+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."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# readme-writing-package
+
+## When to use
+
+- Creating a README for a package, library, SDK, or framework extension
+- 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 when:
+
+- 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. 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** — 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
+- **Re-analyze every time** — never write from cached knowledge; verify the manifest, source, and CI matrix in this session
+- **Preserve existing visual identity** — banner, badges, hero images, and logo lockups stay byte-identical unless the user explicitly asks to change them
+
+## Procedure
+
+### 0. Re-analysis gate — MANDATORY before any writing
+
+Before drafting, produce an evidence ledger from a fresh inspection of
+the package — manifest, source, CI, examples. Do not rely on prior turns
+or the existing README prose.
+
+```
+ledger:
+  package:       <name + version from manifest>
+  description:   <verbatim from manifest>
+  install_cmd:   <verified against the manifest's package manager>
+  requirements:  <language version, framework version, ext-*, services>
+  public_api:    <entry classes / functions / exports from source>
+  test_command:  <real command from manifest scripts / Taskfile>
+  doc_targets:   <list of /docs files actually linked from the new draft>
+  visual_keep:   <line range of existing README header / banner / badges to preserve>
+```
+
+If any cell is unknown, run `ls`, `grep`, `find`, or read the file before
+writing — never invent. When the user asks to keep the existing banner
+or badge row, reproduce it byte-for-byte from the source.
+
+### 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
+
+Read and **verify** files that define actual package behavior (confirm each claim against the source — never paraphrase from memory):
+
+- Manifest: `composer.json`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, or `*.gemspec` — name, description, requirements, scripts
+- Source entrypoints — public API surface, main classes/functions
+- Config files — publishable configs, defaults
+- 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
+
+Extract: package 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 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 or team project
+10. **License** — if applicable
+
+Skip sections that have no real content. Never pad.
+
+### 4. Write requirements and compatibility
+
+State only what is tested and supported. Pull the values from the package's manifest, not from memory. Examples per stack:
+
+```
+## Requirements (PHP)
+
+- PHP ^8.2
+- Laravel 11.x (optional integration)
+- ext-json
+```
+
+```
+## Requirements (JS / TS)
+
+- Node.js >= 20
+- TypeScript >= 5.4 (for typed consumers)
+- npm / pnpm / yarn / bun
+```
+
+```
+## Requirements (Python)
+
+- Python >= 3.11
+- pip / poetry / uv
+- Optional: `fastapi >= 0.110` for the FastAPI integration
+```
+
+```
+## Requirements (Go)
+
+- Go >= 1.22
+```
+
+```
+## Requirements (Rust)
+
+- Rust >= 1.78 (stable)
+- `cargo` workspace member or standalone crate
+```
+
+```
+## Requirements (Ruby)
+
+- Ruby >= 3.2
+- Bundler >= 2.5
+- Optional: Rails 7.1+ for the Rails integration
+```
+
+Do NOT imply broad compatibility if only tested in a narrow range.
+Include language version, framework version, required extensions, and services.
+
+### 5. Write installation that actually works
+
+Document the exact install command and any required follow-up. Use the
+package manager native to the stack — never edit manifests by hand.
+
+```bash
+# PHP / Composer
+composer require vendor/package
+# Optional Laravel integration:
+php artisan vendor:publish --tag=package-config
+```
+
+```bash
+# JS / TS — pick whichever the consumer uses
+npm install <package>
+pnpm add <package>
+yarn add <package>
+bun add <package>
+```
+
+```bash
+# Python
+pip install <package>
+poetry add <package>
+uv add <package>
+```
+
+```bash
+# Go
+go get github.com/<owner>/<package>@latest
+```
+
+```bash
+# Rust
+cargo add <package>
+```
+
+```bash
+# Ruby
+bundle add <package>
+# or, for a standalone gem:
+gem install <package>
+```
+
+Validate each step against the actual codebase.
+Include post-install steps (config publish, service / module / provider
+registration, env vars, codegen, migrations) if the package requires them.
+
+### 6. Write the minimal working example
+
+**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 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 for packages:
+
+```
+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
+```
+
+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, and anti-patterns (premature
+splitting, duplication between README and `/docs/`).
+
+#### Per-AI catalog pattern (multi-platform AI / CLI packages)
+
+For packages that target many AI assistants or platforms (CLI installers,
+agent-config tools, language SDKs with 10+ targets), prefer a flat per-AI
+catalog over a giant matrix. One line per target, install command on the
+left, aligned trailing comment naming the platform:
+
+```bash
+npx <package> init --tools=claude-code      # Claude Code
+npx <package> init --tools=cursor           # Cursor
+npx <package> init --tools=windsurf         # Windsurf
+# ... one line per supported target
+```
+
+Pair the catalog with a separate "Global install" subsection (same flags
+plus `--global`) and an "Other commands" subsection. Reference example:
+[`README.md § Pick specific AIs`](../../../README.md#pick-specific-ais) in
+this repository. Inspiration:
+[`ui-ux-pro-max-skill § Installation`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill#installation).
+
+Use the catalog when the package's primary install action varies by
+platform; use a matrix table (Tool / Rules / Skills / Commands) for
+capability comparison. They serve different jobs — install vs. coverage.
+
+README = enough to adopt. Docs = enough to master.
+
+### 8. Validate links and detect orphans — MANDATORY
+
+For every internal link in the new draft:
+
+1. Resolve the path. `test -f` files, `test -d` directories. Strip
+   `#anchor` and `?query` before the check.
+2. For every anchor link, grep the target for the heading slug.
+3. Build the **link-delta** vs. the old README — `kept` / `added` /
+   `dropped`. For every `dropped` target, search the rest of the repo
+   (`grep -r` over `AGENTS.md`, `docs/`, `dist/agent-src*/`, `packages/`).
+   No other reference → mark **orphan-candidate**.
+
+Surface the orphan-candidate list to the user — never delete silently.
+
+### 9. Validate
+
+- [ ] Install command is correct and complete
+- [ ] Compatibility/requirements match the manifest (`composer.json`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.gemspec`) and the CI matrix
+- [ ] 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 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 contract** — within ~40 lines: name, one-sentence pitch, install command, requirements (or pointer)
+- [ ] Banner / badges / hero from Step 0 visual_keep are byte-identical to source
+- [ ] Every internal link resolved per Step 8 — zero broken file or anchor links
+- [ ] Orphan-candidate list produced even if empty
+
+## Output format
+
+1. Full README draft
+2. Detected package type + audience
+3. Compatibility summary
+4. **Link delta** — `kept` / `added` / `dropped` with orphan-candidates flagged
+5. Evidence ledger (Step 0) so the user can audit assumptions
+6. Uncertainties needing confirmation
+7. Suggested follow-up docs if README would become too large
+
+## Gotcha
+
+- 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 the actual manifest (`composer.json`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.gemspec`) and source, not the old prose
+- Model forgets post-install steps (config publish, service / module / provider registration, env vars, codegen, migrations) — list whichever the stack requires
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every package README you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the package README opens
+  with one sentence: what installs, what it does.
+- Per the cite-don't-restate principle, link upstream docs for
+  advanced topics; ship the minimal usage example only.
+- Per the post-action summary suppression, no "What's new" block —
+  that belongs in `CHANGELOG.md`.
+
+**Pre-save self-check:**
+1. Does the opening pitch include marketing adjectives?
+2. Is the minimal usage example over 10 lines when 5 would suffice?
+3. Are CI badges shipped without verifying that they resolve?
+4. Does the doc duplicate CHANGELOG content?
+
+## 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 present in the repo
+- Do NOT hide requirements or version constraints
+- Do NOT write a giant example when a 10-line one would do
+- Do NOT overload README with reference material — link to /docs