@event4u/agent-config 5.10.1 → 6.1.0

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

@@ -1,350 +0,0 @@
----
-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/`, `.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

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

@@ -1,200 +0,0 @@
----
-model_tier: high
-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
-domain: process
-workspaces:
-  - engineering
-packs:
-  - engineering-base
----
-
-# receiving-code-review
-
-## When to use
-
-* A PR has review comments (from bots like Copilot, Greptile, Augment,
-  or from human reviewers) and the next step is to address them
-* Someone pasted review feedback into the conversation 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)
-* The user explicitly asks for blind implementation of a specific change
-  that is not framed as review feedback
-* The feedback is pure style/formatting that a linter should decide
-  automatically — just 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 —
-it 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 comment
-#5. Group them:
-
-* **Blocking** — breaks behavior, introduces a bug, security issue
-* **Important** — logic is correct but design / readability issue
-* **Minor** — naming, comment style, formatting the linter missed
-* **Wrong** — reviewer misunderstood the code, or suggestion would
-  regress 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."*
-
-If you 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 comment classified as blocking/important:
-
-* 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 — the current code may be the way it is
-  for a reason
-* **Consult memory for prior context.** Via
-  [`memory-access`](../../../docs/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 is right, fix is local, no caller impact | Implement, reference the comment in the commit message |
-| Reviewer is right but fix affects other callers | Note the downstream effects in the reply, then implement |
-| Reviewer is wrong — based on 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
-
-* For 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 existing `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 them into a single commit)
-4. Wrong / YAGNI: no code change, only a reply with reasoning
-
-Run the 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.
-  They frequently flag false positives on patterns the codebase uses
-  deliberately. Verify like you would a human comment.
-* A comment that reads like a question ("should this be X?") is often
-  a polite way of saying "change it to X". Ask if unclear instead of
-  guessing the register.
-* Resolving a comment in the GitHub UI without an accompanying fix or
-  reply silently marks it handled — reviewers may not notice 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. The code change itself is the acknowledgement.
-
-## 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 the 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 has been read, classified, and has a decision
-* [ ] No comment was implemented without a one-sentence restatement
-* [ ] Every implemented fix has been verified by a test or runtime check
-* [ ] Every rejected comment has a reply quoting evidence
-* [ ] No comment was marked resolved without code change or reply
-* [ ] No reply contains flattery
-* [ ] Linters and relevant tests pass after the changes