nitm-ai-dev-toolkit 3.0.15

package/src/repo/.agents/skills/ponytail-audit/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ponytail-audit
+description: >
+  Whole-repo audit for over-engineering. Like ponytail-review, but scans the
+  entire codebase instead of a diff: a ranked list of what to delete, simplify,
+  or replace with stdlib/native equivalents. Use when the user says "audit this
+  codebase", "audit for over-engineering", "what can I delete from this repo",
+  "find bloat", "ponytail-audit", or "/ponytail-audit". One-shot report, does
+  not apply fixes.
+---
+
+ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank
+findings biggest cut first.
+
+## Tags
+
+Same as ponytail-review:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Hunt
+
+Deps the stdlib or platform already ships, single-implementation interfaces,
+factories with one product, wrappers that only delegate, files exporting one
+thing, dead flags and config, hand-rolled stdlib.
+
+## Output
+
+One line per finding, ranked: `<tag> <what to cut>. <replacement>. [path]`.
+End with `net: -<N> lines, -<M> deps possible.` Nothing to cut: `Lean already. Ship.`
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass. Lists findings, applies nothing. One-shot.
+"stop ponytail-audit" or "normal mode" to revert.

package/src/repo/.agents/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ponytail-debt
+description: >
+  Harvest every `ponytail:` comment in the codebase into a debt ledger, so the
+  deliberate shortcuts and deferrals ponytail leaves behind get tracked instead
+  of rotting into "later means never". Use when the user says "ponytail debt",
+  "/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail
+  ledger", or "what did we mark to do later". One-shot report, changes nothing.
+---
+
+Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
+its ceiling and upgrade path. This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
+output:
+
+`grep -rnE '(#|//) ?ponytail:' .`  (add other comment prefixes if your stack uses them)
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger.
+
+## 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 `ponytail: <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 `ponytail:` 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 ponytail: 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. "stop ponytail-debt" or
+"normal mode" to revert.

package/src/repo/.agents/skills/ponytail-gain/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ponytail-gain
+description: >
+  Show ponytail's measured impact as a compact scoreboard: less code, less
+  cost, more speed, from the benchmark medians. One-shot display, not a
+  persistent mode, and not a per-repo number. Trigger: /ponytail-gain,
+  "ponytail gain", "what does ponytail save", "show ponytail impact",
+  "ponytail scoreboard".
+---
+
+# Ponytail Gain
+
+Display this scoreboard when invoked. One-shot: do NOT change mode, write flag
+files, or persist anything.
+
+The figures are the published benchmark medians (5 everyday tasks: email
+validator, debounce, CSV sum, countdown timer, rate limiter; three models:
+Haiku, Sonnet, Opus). They are measured, not computed from the current repo.
+Source: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
+benchmarks and README.
+
+## Scoreboard
+
+Render plain ASCII bars. The bar length shows the measured range; the label
+carries the exact figure:
+
+```
+  ponytail gain                     benchmark median · 5 tasks · 3 models
+
+  Lines of code   no-skill  ████████████████████  100%
+                  ponytail  ██▌·················    6–20%   ▼ 80–94%
+  Cost            no-skill  ████████████████████  100%
+                  ponytail  █████▌··············   23–53%  ▼ 47–77%
+  Speed           ponytail  ▸ 3–6× faster
+
+  This repo:  /ponytail-debt  (shortcuts you deferred)
+              /ponytail-audit (what's still cuttable)
+```
+
+## Honesty boundary
+
+These are benchmark medians, not this repo. NEVER print a per-repo savings
+number ("you saved X lines/tokens here"): the unbuilt version was never
+written, so there is no real baseline to subtract from in a live repo. The
+only real per-repo figures come from `/ponytail-debt` (a counted ledger), and
+this card points there instead of inventing one.
+
+## Boundaries
+
+One-shot display. Edits nothing, changes no mode.
+"stop ponytail" or "normal mode": revert.

package/src/repo/.agents/skills/ponytail-help/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ponytail-help
+description: >
+  Quick-reference card for all ponytail modes, skills, and commands.
+  One-shot display, not a persistent mode. Trigger: /ponytail-help,
+  "ponytail help", "what ponytail commands", "how do I use ponytail".
+---
+
+# Ponytail Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/ponytail lite` | Build what's asked, name the lazier alternative in one line. |
+| **Full** | `/ponytail` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
+| **Ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **ponytail** | `/ponytail` | Lazy mode itself. Simplest solution that works. |
+| **ponytail-audit** | `/ponytail-audit` | Whole-repo over-engineering audit. |
+| **ponytail-debt** | `/ponytail-debt` | Harvest `ponytail:` comments into a tracked ledger. |
+| **ponytail-review** | `/ponytail-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
+| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
+| **ponytail-help** | `/ponytail-help` | This card. |
+
+Codex uses `@ponytail`, `@ponytail-review`, and `@ponytail-help`; Claude Code
+and OpenCode use the slash-command forms above. OpenCode ships all six slash
+commands (`/ponytail`, `/ponytail-audit`, `/ponytail-debt`, `/ponytail-review`,
+`/ponytail-gain`, `/ponytail-help`).
+
+## Deactivate
+
+Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
+`/ponytail off` also works.
+
+## Configure Default Mode
+
+Default mode = `full`, auto-active every session. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export PONYTAIL_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start, activate manually
+with `/ponytail` when wanted.
+
+Resolution: env var > config file > `full`.
+
+## Update
+
+This toolkit ships ponytail as templates, so updating is the same as updating the
+ai-assisted-dev-toolkit: pull the latest version of this repo. If you installed
+ponytail separately as a Claude Code plugin, use `/plugin marketplace update
+ponytail` then `/reload-plugins`. Other hosts use their own update flow — see
+the host's documentation.
+
+## More
+
+Full docs + examples: https://github.com/DietrichGebert/ponytail

package/src/repo/.agents/skills/ponytail-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ponytail-review
+description: >
+  Code review focused exclusively on over-engineering. Finds what to delete:
+  reinvented standard library, unneeded dependencies, speculative abstractions,
+  dead flexibility. One line per finding: location, what to cut, what replaces
+  it. Use when the user says "review for over-engineering", "what can we
+  delete", "is this over-engineered", "simplify review", or invokes
+  /ponytail-review. Complements correctness-focused review, this one only
+  hunts complexity.
+---
+
+Review diffs for unnecessary complexity. One line per finding: location, what
+to cut, what replaces it. The diff's best outcome is getting shorter.
+
+## Format
+
+`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
+multi-file diffs.
+
+Tags:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Examples
+
+❌ "This EmailValidator class might be more complex than necessary, have you
+considered whether all these validation rules are needed at this stage?"
+
+✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`
+
+✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
+
+✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
+
+✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
+
+✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`
+
+## Scoring
+
+End with the only metric that matters: `net: -<N> lines possible.`
+
+If there is nothing to cut, say `Lean already. Ship.` and stop.
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass, not this one. A single smoke test or `assert`-based
+self-check is the ponytail minimum, not bloat, never flag it for deletion.
+Does not apply the fixes, only lists them.
+"stop ponytail-review" or "normal mode": revert to verbose review style.

package/src/repo/.agents/skills/project-documentation/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: project-documentation
+description: Standards for creating and maintaining project documentation including README files, inline comments, API documentation, and architectural decision records
+version: 1.0.0
+author: {{PROJECT_NAME}} Team
+created: 2026-01-26
+updated: 2026-01-26
+tags:
+  - documentation
+  - readme
+  - api-docs
+  - adr
+  - comments
+applies_to:
+  - "**/*.md"
+  - "**/README*"
+  - "**/CHANGELOG*"
+  - "**/docs/**"
+---
+
+# Project Documentation Standards
+
+Comprehensive guidelines for creating clear, consistent, and maintainable documentation across the project.
+
+## Documentation Hierarchy
+
+### Required Documentation
+
+| File           | Location     | Purpose                              |
+| -------------- | ------------ | ------------------------------------ |
+| `README.md`    | Project root | Project overview, setup, quick start |
+| `AGENTS.md`    | Project root | AI agent context and patterns        |
+| `CHANGELOG.md` | Project root | Version history and changes          |
+| `docs/`        | Project root | Detailed documentation               |
+
+### Documentation Types
+
+```
+{{PROJECT_NAME}}/
+├── README.md                    # Quick start, overview
+├── AGENTS.md                    # AI context
+├── CHANGELOG.md                 # Version history
+├── CONTRIBUTING.md              # Contribution guidelines
+└── docs/
+    ├── architecture/            # System design
+    │   ├── overview.md
+    │   └── decisions/           # ADRs
+    ├── api/                     # API documentation
+    ├── guides/                  # How-to guides
+    ├── specs/                   # Feature specifications
+    └── fixes/                   # Bug fix documentation
+```
+
+## README.md Standards
+
+### Required Sections
+
+Every README.md should include:
+
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+
+# Installation
+
+{{PACKAGE_MANAGER}} install
+
+# Development
+
+{{PACKAGE_MANAGER}} run dev
+
+# Testing
+
+{{PACKAGE_MANAGER}} run test
+\`\`\`
+
+## Features
+
+- Feature 1: Description
+- Feature 2: Description
+
+## Documentation
+
+- [Full Documentation](./docs/)
+- [API Reference](./docs/api/)
+- [Contributing](./CONTRIBUTING.md)
+
+## License
+
+{{LICENSE_TYPE}}
+```
+
+### README Best Practices
+
+**✅ DO:**
+
+- Start with a clear one-line description
+- Include badges (build status, version, license)
+- Provide copy-paste ready commands
+- Link to detailed documentation
+- Include screenshots/GIFs for UI projects
+- Keep the quick start under 5 commands
+
+**❌ DON'T:**
+
+- Include implementation details
+- Document every configuration option
+- Repeat information from other docs
+- Use jargon without explanation
+- Assume prior knowledge of the stack
+
+## Code Comments Standards
+
+### When to Comment
+
+**Comment WHY, not WHAT:**
+
+```{{FILE_EXTENSION}}
+// ❌ BAD - Describes what the code does (obvious from reading)
+// Loop through users and check each one
+for (const user of users) {
+    if (user.isActive) { ... }
+}
+
+// ✅ GOOD - Explains why this approach was chosen
+// Check active users first to fail fast on permission errors
+// before expensive database operations
+for (const user of users) {
+    if (user.isActive) { ... }
+}
+```
+
+### Comment Types
+
+#### File Headers
+
+```{{FILE_EXTENSION}}
+/**
+ * {{COMPONENT_NAME}}
+ *
+ * Purpose: Brief description of the file's responsibility
+ *
+ * Dependencies:
+ * - ServiceA: For data fetching
+ * - UtilityB: For formatting
+ *
+ * @see docs/architecture/components.md for design decisions
+ */
+```
+
+#### Function Documentation
+
+```{{FILE_EXTENSION}}
+/**
+ * Calculates the user's engagement score based on activity metrics.
+ *
+ * The algorithm weighs recent activity higher than historical data
+ * to reflect current engagement levels accurately.
+ *
+ * @param userId - The unique identifier of the user
+ * @param timeRange - Period to analyze (default: 30 days)
+ * @returns Engagement score between 0-100, or null if insufficient data
+ *
+ * @example
+ * const score = await calculateEngagementScore('user-123', { days: 7 });
+ * if (score > 80) { // Highly engaged user }
+ *
+ * @throws {UserNotFoundError} When userId doesn't exist
+ * @see docs/algorithms/engagement.md for scoring methodology
+ */
+```
+
+#### Inline Comments
+
+```{{FILE_EXTENSION}}
+// IMPORTANT: This order matters - auth must happen before rate limiting
+await authenticate(request);
+await checkRateLimit(request);
+
+// TODO(username): Refactor when API v2 is released - JIRA-123
+const legacyAdapter = createAdapter();
+
+// HACK: Workaround for browser bug in Safari 16.x
+// Remove after Safari 17 reaches 90% adoption
+if (isSafari16) { ... }
+
+// NOTE: This seems slow but is optimized by the runtime
+// See benchmarks: docs/performance/query-optimization.md
+const result = data.filter(...).map(...).reduce(...);
+```
+
+### Comment Tags
+
+| Tag          | Usage                   |
+| ------------ | ----------------------- |
+| `TODO`       | Planned improvements    |
+| `FIXME`      | Known issues to address |
+| `HACK`       | Temporary workarounds   |
+| `NOTE`       | Important context       |
+| `IMPORTANT`  | Critical information    |
+| `DEPRECATED` | Code to be removed      |
+| `SECURITY`   | Security-sensitive code |
+
+## API Documentation
+
+### Endpoint Documentation
+
+```markdown
+## POST /api/users
+
+Create a new user account.
+
+### Request
+
+\`\`\`json
+{
+"email": "user@example.com",
+"name": "John Doe",
+"role": "member"
+}
+\`\`\`
+
+### Response
+
+**201 Created**
+\`\`\`json
+{
+"id": "usr_123",
+"email": "user@example.com",
+"name": "John Doe",
+"createdAt": "2026-01-26T10:00:00Z"
+}
+\`\`\`
+
+**400 Bad Request**
+\`\`\`json
+{
+"error": "VALIDATION_ERROR",
+"message": "Email already exists"
+}
+\`\`\`
+
+### Notes
+
+- Requires authentication
+- Rate limited: 10 requests/minute
+```
+
+## Architectural Decision Records (ADRs)
+
+### ADR Template
+
+```markdown
+# ADR-001: {{DECISION_TITLE}}
+
+## Status
+
+Accepted | Proposed | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision?
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+### Positive
+
+- Benefit 1
+- Benefit 2
+
+### Negative
+
+- Tradeoff 1
+- Tradeoff 2
+
+## References
+
+- [Related document](link)
+- [Prior discussion](link)
+```
+
+### When to Write ADRs
+
+- Significant technology choices
+- Architecture pattern decisions
+- Breaking changes to APIs
+- Security-related decisions
+- Performance optimization approaches
+
+## Changelog Standards
+
+### Format (Keep a Changelog)
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- New feature description
+
+### Changed
+
+- Modified behavior description
+
+### Deprecated
+
+- Soon-to-be removed features
+
+### Removed
+
+- Removed features
+
+### Fixed
+
+- Bug fix descriptions
+
+### Security
+
+- Security vulnerability fixes
+
+## [1.0.0] - 2026-01-26
+
+### Added
+
+- Initial release
+```
+
+## Documentation Quality Checklist
+
+### Before Committing
+
+- [ ] README updated if behavior changed
+- [ ] Public functions have JSDoc/docstrings
+- [ ] Complex logic has explanatory comments
+- [ ] Breaking changes documented in CHANGELOG
+- [ ] New features have usage examples
+- [ ] Error messages are documented
+
+### Review Criteria
+
+- [ ] Documentation matches implementation
+- [ ] Examples are copy-paste ready
+- [ ] Links are not broken
+- [ ] Code samples are syntax-highlighted
+- [ ] Screenshots are up-to-date
+
+## Related Skills
+
+- See `.agents/skills/writing-skills/` for prompt writing guidelines
+- See `.agents/skills/writing-plans/` for feature planning documentation