@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/.claude/skills/ponytail/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Ponytail"
+  short_description: "Lazy senior dev mode: the smallest change that fully solves the task, and a reply a..."

package/.claude/skills/ponytail-audit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: ponytail-audit
+description: >
+  Quality audit of a whole repo: bugs, security holes, what breaks under real
+  load, risky code without tests, slow paths, and what to delete, merge or
+  split. Ranked, each finding explained in plain English. One-shot report,
+  changes nothing. Use for "audit this codebase", "review the whole repo",
+  "find bloat", "what can I delete", /ponytail-audit.
+---
+
+Audit the whole repo like the senior developer who just inherited it and
+will be paged when it breaks. Order of importance: correct, safe, holds under
+load, tested, fast, lean. Lean still matters: every extra line must be read,
+tested and fixed later. This is a report the user asked for, so give it in full.
+
+## 1. Map first
+
+- Audit what the user names: a folder, a package, or the whole repo.
+  Nothing named: the whole repo.
+- Read the README, the deploy and build config, the dependency list, the
+  entry points (main, routes, handlers, jobs, CLI commands) and the tests.
+- Find the expected load: one person running a script, or many users and
+  processes at once. Judge scale against that, and say which load you assumed.
+- Trace the main flows end to end: where data comes in, what is stored,
+  what goes out. Read those paths fully: input from users, money, auth,
+  data writes, background jobs, anything shared between processes.
+- Big repo: go deep where a mistake costs the most, not file by file. Say
+  which parts you did not read.
+
+## 2. Look for
+
+1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
+   rounding, time zones), callers that disagree with what a function returns,
+   the same rule applied differently in two places.
+2. **Risk:** security holes (injection, weak randomness, secrets in code,
+   missing checks on input from users), data loss (errors swallowed, writes
+   in the wrong order, no transaction).
+3. **Scale:** fine for one user, wrong for many: check-then-write races, the
+   same work done by every process, memory or lists that only grow, a query
+   per item, O(n^2) on big input, per-process state that must be shared.
+4. **Missing test:** risky logic (a branch, a parser, money, security, data
+   writes) with no test that fails when it breaks. One good test, not coverage.
+5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
+   loop) are suggestions; some software counts every millisecond.
+6. **Lean:** code that should not exist or should be smaller.
+   - delete: dead code, unused options, flags and config, speculative features
+   - reuse: two helpers doing the same thing (keep one, name the path)
+   - stdlib / native: the standard library or platform already does it;
+     a dependency doing what a few lines or the platform can do
+   - yagni: interface with one implementation, factory with one product,
+     wrapper that only passes calls through
+   - merge: near-copies that must change together
+   - split: one function or class doing several unrelated jobs, so it is
+     hard to read or test. Split by job, never by line count, and never into
+     helpers that exist only to make a function shorter.
+
+## 3. Check before you report
+
+- Every finding needs a concrete case: "this input or situation leads to this
+  wrong result". No case, no finding.
+- Before calling code unused, grep the whole tree for it, including tests,
+  fixtures, config, and string or dynamic references.
+- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit is a
+  decision, not a finding, unless the expected load already crosses it.
+- Propose the smallest fix that works. Prefer fixes that delete code. Never
+  add layers, frameworks or config the problem does not need.
+- No style taste, no "consider", no vague worries.
+
+## 4. Output
+
+Very simple English: short sentences, everyday words. Explain a technical
+term the first time you use it. The reader may never have seen this code.
+
+Start with `What this repo does:` in two or three sentences, and the load
+you assumed.
+
+Then the findings in three groups, most important first, skip empty groups:
+- **Must fix:** bug, security, data loss, breaks at the expected load.
+- **Should fix:** risky code without a test, real slowness, duplication, a
+  function that mixes jobs, code that should not exist.
+- **Nice to have:** small speed-ups, shorter forms.
+
+Number findings across all groups, so the user can say "fix 2 and 5". At
+most 20 findings; if you left smaller ones out, say how many.
+Every finding has all four parts, each one or two short sentences:
+
+2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
+   - **What this is:** At midnight this job closes the day and bills all orders of that day.
+   - **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
+     at 00:30 in Berlin is billed on the day before.
+   - **Fix:** Compute the day once in the shop's time zone:
+     `datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
+   - **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
+
+End with:
+- `Verdict:` one line: healthy, or what to fix first.
+- `Lean: -<N> lines, -<M> dependencies possible.` when lean findings exist.
+- `Not checked:` the parts you did not read or could not run.
+
+Nothing found: `What this repo does:`, then `Healthy. Nothing to fix.` and
+one line on what you checked.
+
+One-shot report, changes no code.

package/.claude/skills/ponytail-audit/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Ponytail Audit"
+  short_description: "Quality audit of a whole repo: bugs, security holes, what breaks under real load,..."

package/.claude/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ponytail-debt
+description: >
+  List every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report,
+  changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the
+  shortcuts", /ponytail-debt.
+---
+
+Every deliberate ponytail shortcut is marked with a `shortcut:` comment naming
+its ceiling and upgrade path (older code may say `ponytail:`). This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `.git` and everything the
+`.gitignore` files ignore (dependencies, build output, caches, in any stack):
+
+`git grep --no-index --exclude-standard -nE '(#|//|/[*]) ?(shortcut|ponytail):'`  (add other comment prefixes if your stack uses them)
+
+If the user names their own marker word (`/ponytail-debt TODO`), grep for that word instead.
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger. Skip hits that are not a deferral, like a note
+about a keyboard shortcut.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `shortcut: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any marker comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No shortcut debt. Clean ledger.`
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot.

package/.claude/skills/ponytail-debt/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Ponytail Debt"
+  short_description: "List every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger."

package/.claude/skills/ponytail-review/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ponytail-review
+description: >
+  Quality review of a change: is the logic right, is it safe, does it hold
+  under real load, is risky code tested, is it fast enough, and is every line
+  needed. Reads the connected code, not only the diff. Each finding is
+  explained in plain English. Use for "review this", "code review", "review
+  the last commit", "review my PR", "is this over-engineered", /ponytail-review.
+---
+
+Review a change like the senior developer who will be paged when it breaks.
+Order of importance: correct, safe, holds under load, tested, fast, lean.
+Lean still matters: every extra line must be read, tested and fixed later.
+This is a report the user asked for, so give it in full.
+
+## 1. Understand first
+
+- Review what the user names: uncommitted or staged changes, a branch, a PR
+  link, or files. Nothing named: the uncommitted changes, or the last commit
+  if there are none.
+- Read the diff, then the code it touches: callers of every changed function,
+  the functions it calls, the tests, the README.
+- Trace the real flow: where data comes in, what is stored, what goes out.
+- A change can break code it does not touch. When a signature, return value
+  or behavior changes, grep every caller.
+- Find the expected load in the repo (README, deploy config): one person
+  running a script, or many users and processes at once. Judge scale against
+  that, and say which load you assumed.
+
+## 2. Look for
+
+1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
+   rounding, time zones), a caller broken by the change, a fix applied in one
+   caller while the shared function stays broken.
+2. **Risk:** security holes (injection, weak randomness, secrets, missing
+   checks on input from users), data loss (errors swallowed, writes in the
+   wrong order, no transaction).
+3. **Scale:** fine for one user, wrong for many: check-then-write races, the
+   same work done by every process, memory or lists that only grow, a query
+   per item, O(n^2) on big input, per-process state that must be shared.
+4. **Missing test:** risky new logic (a branch, a parser, money, security,
+   data writes, a bug fix) with no test that fails when it breaks. One good
+   test, not coverage.
+5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
+   loop) are suggestions; some software counts every millisecond.
+6. **Lean:** code that should not exist or should be smaller.
+   - delete: dead code, unused options, speculative features
+   - reuse: the repo already has this helper (name the path)
+   - stdlib / native: the standard library or platform already does it; a
+     new dependency for a few lines
+   - yagni: abstraction with one implementation, config nobody sets
+   - merge: near-copies that must change together
+   - split: one function doing several unrelated jobs, so it is hard to read
+     or test. Split by job, never by line count, and never into helpers that
+     exist only to make a function shorter.
+
+## 3. Check before you report
+
+- Every finding needs a concrete case: "this input or situation leads to this
+  wrong result". No case, no finding.
+- Re-read the lines and confirm: the caller exists, the value can really be
+  empty, the code really is unused.
+- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit is a
+  decision, not a finding, unless the expected load already crosses it.
+- Propose the smallest fix that works. Prefer fixes that delete code. Never
+  add layers, frameworks or config the problem does not need.
+- No style taste, no "consider", no vague worries.
+
+## 4. Output
+
+Very simple English: short sentences, everyday words. Explain a technical
+term the first time you use it. The reader may never have seen this code.
+
+Start with `What this change does:` in two or three sentences.
+
+Then the findings in three groups, skip empty groups:
+- **Must fix:** bug, security, data loss, breaks at the expected load.
+- **Should fix:** risky code without a test, real slowness, duplication, a
+  function that mixes jobs, code that should not exist.
+- **Nice to have:** small speed-ups, shorter forms.
+
+Number findings across all groups, so the user can say "fix 2 and 5".
+Every finding has all four parts, each one or two short sentences:
+
+2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
+   - **What this is:** At midnight this job closes the day and bills all orders of that day.
+   - **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
+     at 00:30 in Berlin is billed on the day before.
+   - **Fix:** Compute the day once in the shop's time zone:
+     `datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
+   - **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
+
+End with:
+- `Verdict: Ship.` or `Verdict: fix 1 and 3 first.`
+- `Lean: -<N> lines possible.` when lean findings exist.
+- `Not checked:` one line, if something mattered and you could not check it.
+
+Nothing found: `What this change does:`, then `Looks good. Ship.` and one line
+on what you checked.
+
+Lists findings, changes no code.

package/.claude/skills/ponytail-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Ponytail Review"
+  short_description: "Quality review of a change: is the logic right, is it safe, does it hold under real..."

package/.claude/skills/postgres-best-practices/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: postgres-best-practices
+description: Best practices and guidelines for working with Postgres. Covers schema design, indexing strategies, query optimization, migrations, and common pitfalls. Use when writing SQL, designing database schemas, optimizing queries, or setting up a Postgres database.
+---
+
+# Postgres Best Practices
+
+Guidelines and best practices for working with Postgres, covering schema design, indexing, query optimization, and common pitfalls.
+
+## Supported Versions
+
+This skill covers PostgreSQL 14 through 18. Version-specific features are tagged (e.g., `[PG15+]`, `[PG18+]`); environment-dependent examples identify required privileges, extensions, or multi-node setup.
+
+PostgreSQL provides 5 years of support per major version. Always run the latest minor release.
+
+| Version | Initial Release    | End of Life        |
+| ------- | ------------------ | ------------------ |
+| 18      | September 2025     | November 2030      |
+| 17      | September 2024     | November 2029      |
+| 16      | September 2023     | November 2028      |
+| 15      | October 2022       | November 2027      |
+| 14      | September 2021     | November 2026      |
+
+Source: [postgresql.org/support/versioning](https://www.postgresql.org/support/versioning/)
+
+## References
+
+| Area                    | Resource                                | When to Use                                                        |
+| ----------------------- | --------------------------------------- | ------------------------------------------------------------------ |
+| Schema Design           | `references/schema-design.md`           | Designing tables, choosing data types, normalizing, partitioning   |
+| Indexing                | `references/indexing.md`                | Choosing index types, composite indexes, partial/covering indexes  |
+| Query Optimization      | `references/query-optimization.md`      | Reading EXPLAIN ANALYZE, fixing bottlenecks, planner tuning        |
+| Query Patterns          | `references/query-patterns.md`          | CTEs, window functions, lateral joins, UPSERT, JSONB, anti-patterns|
+| Performance Diagnostics | `references/performance-diagnostics.md` | pg_stat views, lock analysis, VACUUM, connection management        |
+| Logical Replication     | `references/logical-replication.md`     | Pub/sub replication, live migrations, CDC                          |
+| Hot Standby             | `references/hot-standby.md`             | Streaming replication, read replicas, failover                     |
+| Transaction Isolation   | `references/transaction-isolation.md`   | Isolation levels, lost updates, serialization failures, retry logic |
+| Backup & Restore        | `references/backup-restore.md`          | pg_dump/pg_restore, pg_basebackup, PITR, recovery                 |
+| Security & Roles        | `references/security-roles.md`          | Privileges, RLS, pg_hba.conf, authentication, SSL                 |
+| Bulk Data Loading       | `references/bulk-loading.md`            | COPY patterns, ETL staging, optimizing large loads, batch ops      |
+| Connection Pooling      | `references/connection-pooling.md`      | PgBouncer config, pool modes, prepared statements, sizing          |
+| Major Version Upgrades  | `references/major-version-upgrades.md`  | pg_upgrade, logical replication migration, pre/post checklists     |

package/.claude/skills/postgres-best-practices/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Postgres Best Practices"
+  short_description: "Best practices and guidelines for working with Postgres."