@jgiox/goodvibes 1.0.0

package/templates/.claude/skills/caveman-compress/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: caveman-compress
+description: >
+  Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format
+  to save input tokens. Preserves all technical substance, code, URLs, and structure.
+  Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md.
+  Trigger: /caveman-compress FILEPATH or "compress memory file"
+---
+
+# Caveman Compress
+
+## Purpose
+
+Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.md`.
+
+## Trigger
+
+`/caveman-compress <filepath>` or when user asks to compress a memory file.
+
+## Process
+
+1. The compression scripts live in `scripts/` (adjacent to this SKILL.md). If the path is not immediately available, search for `scripts/__main__.py` next to this SKILL.md.
+
+2. From the directory containing this SKILL.md, run:
+
+python3 -m scripts <absolute_filepath>
+
+3. The CLI will:
+- detect file type (no tokens)
+- call Claude to compress
+- validate output (no tokens)
+- if errors: cherry-pick fix with Claude (targeted fixes only, no recompression)
+- retry up to 2 times
+- if still failing after 2 retries: report error to user, leave original file untouched
+
+4. Return result to user
+
+## Compression Rules
+
+### Remove
+- Articles: a, an, the
+- Filler: just, really, basically, actually, simply, essentially, generally
+- Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
+- Hedging: "it might be worth", "you could consider", "it would be good to"
+- Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
+- Connective fluff: "however", "furthermore", "additionally", "in addition"
+
+### Preserve EXACTLY (never modify)
+- Code blocks (fenced ``` and indented)
+- Inline code (`backtick content`)
+- URLs and links (full URLs, markdown links)
+- File paths (`/src/components/...`, `./config.yaml`)
+- Commands (`npm install`, `git commit`, `docker build`)
+- Technical terms (library names, API names, protocols, algorithms)
+- Proper nouns (project names, people, companies)
+- Dates, version numbers, numeric values
+- Environment variables (`$HOME`, `NODE_ENV`)
+
+### Preserve Structure
+- All markdown headings (keep exact heading text, compress body below)
+- Bullet point hierarchy (keep nesting level)
+- Numbered lists (keep numbering)
+- Tables (compress cell text, keep structure)
+- Frontmatter/YAML headers in markdown files
+
+### Compress
+- Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
+- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
+- Drop "you should", "make sure to", "remember to" — just state the action
+- Merge redundant bullets that say the same thing differently
+- Keep one example where multiple examples show the same pattern
+
+CRITICAL RULE:
+Anything inside ``` ... ``` must be copied EXACTLY.
+Do not:
+- remove comments
+- remove spacing
+- reorder lines
+- shorten commands
+- simplify anything
+
+Inline code (`...`) must be preserved EXACTLY.
+Do not modify anything inside backticks.
+
+If file contains code blocks:
+- Treat code blocks as read-only regions
+- Only compress text outside them
+- Do not merge sections around code
+
+## Pattern
+
+Original:
+> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
+
+Compressed:
+> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
+
+Original:
+> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.
+
+Compressed:
+> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
+
+## Boundaries
+
+- ONLY compress natural language files (.md, .txt, .typ, .typst, .tex, extensionless)
+- NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh
+- If file has mixed content (prose + code), compress ONLY the prose sections
+- If unsure whether something is code or prose, leave it unchanged
+- Original file is backed up as FILE.original.md before overwriting
+- Never compress FILE.original.md (skip it)

package/templates/.claude/skills/caveman-help/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: caveman-help
+description: >
+  Quick-reference card for all caveman modes, skills, and commands.
+  One-shot display, not a persistent mode. Trigger: /caveman-help,
+  "caveman help", "what caveman commands", "how do I use caveman".
+---
+
+# Caveman Help
+
+Display this reference card when invoked. One-shot — do NOT change mode, write flag files, or persist anything. Output in caveman style.
+
+## Modes
+
+| Mode | Trigger | What change |
+|------|---------|-------------|
+| **Lite** | `/caveman lite` | Drop filler. Keep sentence structure. |
+| **Full** | `/caveman` | Drop articles, filler, pleasantries, hedging. Fragments OK. Default. |
+| **Ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Tables over prose. |
+| **Wenyan-Lite** | `/caveman wenyan-lite` | Classical Chinese style, light compression. |
+| **Wenyan-Full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness. |
+| **Wenyan-Ultra** | `/caveman wenyan-ultra` | Extreme. Ancient scholar on a budget. |
+
+Mode stick until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it do |
+|-------|---------|-----------|
+| **caveman-commit** | `/caveman-commit` | Terse commit messages. Conventional Commits. ≤50 char subject. |
+| **caveman-review** | `/caveman-review` | One-line PR comments: `L42: bug: user null. Add guard.` |
+| **caveman-compress** | `/caveman-compress <file>` | Compress .md files to caveman prose. Saves ~46% input tokens. |
+| **caveman-help** | `/caveman-help` | This card. |
+
+## Deactivate
+
+Say "stop caveman" or "normal mode". Resume anytime with `/caveman`.
+
+## Language
+
+Keep user's language by default. User write Portuguese → reply Portuguese caveman. Compress the style, not the language. Technical terms, code, commands, commit types, and exact error strings stay verbatim unless user ask for translation.
+
+## Configure Default Mode
+
+Default mode = `full`. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export CAVEMAN_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/caveman/config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start. User can still activate manually with `/caveman`.
+
+Resolution: env var > config file > `full`.
+
+## More
+
+Full docs: https://github.com/JuliusBrussee/caveman

package/templates/.claude/skills/caveman-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: caveman-review
+description: >
+  Ultra-compressed code review comments. Cuts noise from PR feedback while preserving
+  the actionable signal. Each comment is one line: location, problem, fix. Use when user
+  says "review this PR", "code review", "review the diff", "/review", or invokes
+  /caveman-review. Auto-triggers when reviewing pull requests.
+---
+
+Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
+
+## Rules
+
+**Format:** `L<line>: <problem>. <fix>.` — or `<file>:L<line>: ...` when reviewing multi-file diffs.
+
+**Severity prefix (optional, when mixed):**
+- `🔴 bug:` — broken behavior, will cause incident
+- `🟡 risk:` — works but fragile (race, missing null check, swallowed error)
+- `🔵 nit:` — style, naming, micro-optim. Author can ignore
+- `❓ q:` — genuine question, not a suggestion
+
+**Drop:**
+- "I noticed that...", "It seems like...", "You might want to consider..."
+- "This is just a suggestion but..." — use `nit:` instead
+- "Great work!", "Looks good overall but..." — say it once at the top, not per comment
+- Restating what the line does — the reviewer can read the diff
+- Hedging ("perhaps", "maybe", "I think") — if unsure use `q:`
+
+**Keep:**
+- Exact line numbers
+- Exact symbol/function/variable names in backticks
+- Concrete fix, not "consider refactoring this"
+- The *why* if the fix isn't obvious from the problem statement
+
+## Examples
+
+❌ "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
+
+✅ `L42: 🔴 bug: user can be null after .find(). Add guard before .email.`
+
+❌ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
+
+✅ `L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.`
+
+❌ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
+
+✅ `L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).`
+
+## Auto-Clarity
+
+Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not just a one-liner), and onboarding contexts where the author is new and needs the "why". In those cases write a normal paragraph, then resume terse for the rest.
+
+## Boundaries
+
+Reviews only — does not write the code fix, does not approve/request-changes, does not run linters. Output the comment(s) ready to paste into the PR. "stop caveman-review" or "normal mode": revert to verbose review style.

package/templates/.claude/skills/caveman-stats/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: caveman-stats
+description: >
+  Show real token usage and estimated savings for the current session.
+  Reads directly from the Claude Code session log — no AI estimation.
+  Triggers on /caveman-stats. Output is injected by the mode-tracker hook;
+  the model itself does not compute the numbers.
+---
+
+This skill is delivered by `hooks/caveman-stats.js` (read by `hooks/caveman-mode-tracker.js` on `/caveman-stats`). The model does not need to do anything when this skill fires — the hook returns `decision: "block"` with the formatted stats as the reason. The user sees the numbers immediately.

package/templates/.claude/skills/goodvibes-hygiene/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: goodvibes-hygiene
+description: >
+  On-demand code minimalism audit using ponytail commands. Wraps /ponytail-review
+  (diff audit) and /ponytail-audit (whole-repo scan) with goodvibes context.
+  Ponytail's always-on rules are already active via CLAUDE.md. Use these commands
+  for explicit on-demand audits.
+  Use when user says "review for over-engineering", "audit for complexity",
+  "check for bloat", "is this over-engineered", or invokes /ponytail-review or
+  /ponytail-audit directly.
+---
+
+# goodvibes hygiene
+
+Ponytail rules are already always-on in your CLAUDE.md. These commands add
+explicit on-demand audits.
+
+## Setup
+
+Ponytail commands require the ponytail plugin. Install it in Claude Code:
+
+```
+/plugin marketplace add DietrichGebert/ponytail
+/plugin install ponytail@ponytail
+```
+
+(Desktop app: Customize → + by personal plugins → Create plugin → Add from repository →
+enter `https://github.com/DietrichGebert/ponytail`)
+
+## Commands
+
+- `/ponytail-review` — Review the current diff for over-engineering. One line per
+  finding: location, what to cut, what replaces it.
+- `/ponytail-audit` — Scan the entire repo for unnecessary complexity. Ranked list,
+  biggest cut first.
+
+## What the always-on rules already do
+
+Every response already applies the ponytail decision ladder (from your CLAUDE.md):
+simplest solution that works, stdlib before custom code, deletion before addition.
+The commands above are for explicit audit reports — use them when you want a
+structured review, not just session behavior.

package/templates/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,54 @@
+name: Bug Report
+description: File a bug report to help us improve this project
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: "What happened?"
+      description: "A clear description of what the bug is"
+      placeholder: "Tell us what you see"
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: "Steps to reproduce"
+      description: "Step-by-step instructions to reproduce the bug"
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: "Expected behavior"
+      description: "What you expected to happen"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: "Project version"
+      placeholder: "e.g. 1.0.0"
+    validations:
+      required: false
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: "Operating system"
+      options:
+        - Linux
+        - macOS
+        - "Windows (WSL2)"
+        - "Windows (native)"
+    validations:
+      required: false

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement! Please fill out the details below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: "What problem does this solve?"
+      description: "Describe the problem or limitation you are running into"
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: "Describe the solution you'd like"
+      description: "What do you want to happen?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Alternatives you've considered"
+      description: "Any other approaches you thought about?"
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: "Before submitting"
+      options:
+        - label: "I searched existing issues and this is not a duplicate."
+          required: true

package/templates/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+<!-- Pull Request: describe your change in the title above -->
+
+## What does this PR do?
+
+> [one sentence: what problem does this fix or feature does this add?]
+
+## Checklist
+
+- [ ] The change does one thing (not multiple unrelated changes).
+- [ ] I tested this manually before opening the PR.
+- [ ] Automated checks pass (CI green, if configured).
+- [ ] I updated relevant docs if my change affects how the project is used.
+- [ ] I have not introduced new TODO comments without a linked issue.

package/templates/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 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/2.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial project setup.

package/templates/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+<!-- goodvibes:start -->
+# goodvibes: v1.0.0
+
+## Engineering Rules
+
+### Before you begin
+For every task, define: the exact request, success criteria, files you expect to touch, tests you expect to run, docs you expect to update. If you cannot state those things clearly, you are not ready to code.
+
+### Think before coding
+**State assumptions explicitly before implementing.**
+- Write down assumptions before editing code.
+- Do not silently choose one interpretation when multiple materially different interpretations exist.
+- If you proceed with an assumption because the task is small and reversible, say so in the PR.
+- If the assumption is security-sensitive, data-sensitive, or schema-sensitive, do not proceed silently.
+
+### Simplicity first
+**Use the minimum code that solves the problem.**
+- Prefer a direct implementation over a generalized one.
+- Prefer one clear function over a new framework layer.
+- Avoid optional flags, plugin hooks, factories, and strategy objects unless the task actually requires them.
+- If 200 lines can be 50 without losing clarity, reduce it.
+
+### Surgical changes
+**Touch only what the task requires.**
+- Keep diffs narrow. Do not opportunistically reformat unrelated files.
+- Do not rename files, symbols, or folders unless the task requires it.
+- Only remove imports, variables, functions, or files that your change made unused.
+- If you notice unrelated dead code, mention it in the PR but do not delete it unless asked.
+
+### Fail loud
+**Do not fail silently.**
+- No empty `catch` blocks. No swallowed exceptions.
+- No silent retries without bounded policy and logging.
+- No returning fake success on real failure.
+- Error messages must be actionable and specific enough to debug.
+
+### Security
+**Security is an engineering requirement, not a cleanup task.**
+- Validate input at the boundary. Encode output to the target context.
+- Use parameterized queries. Keep secrets out of code, commits, and logs.
+- Apply least privilege for tokens, roles, and permissions.
+
+Must flag immediately: SQL injection, XSS, command injection, path traversal, broken auth, leaked secrets, unsafe dependency additions.
+
+### Journal
+**Update `JOURNAL.md` at the end of every task.**
+Each entry must include: date, task summary, files changed, why the change was made, tests run, docs updated.
+Rules: do not rewrite history. Additive entries only. Keep it short, factual, and readable.
+
+## Ponytail — Minimalism Ruleset
+
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
+
+## Persistence
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
+unsure. Off only: "stop ponytail" / "normal mode". Default: **full**.
+Switch: `/ponytail lite|full|ultra`.
+
+## The ladder
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** Use it.
+5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+## Rules
+- No unrequested abstractions: no interface with one implementation, no factory for one product.
+- No boilerplate, no scaffolding "for later".
+- Deletion over addition. Boring over clever.
+- Fewest files possible. Shortest working diff wins.
+- Mark deliberate simplifications with a `ponytail:` comment.
+
+## Output
+Code first. Then at most three short lines: what was skipped, when to add it.
+
+## Intensity
+| Level | What changes |
+|-------|------------|
+| **lite** | Build what's asked, name the lazier alternative in one line. |
+| **full** | The ladder enforced. Shortest diff, shortest explanation. Default. |
+| **ultra** | YAGNI extremist. Deletion before addition. |
+
+## When NOT to be lazy
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it.
+
+Never lazy about understanding the problem. Trace the whole thing first.
+<!-- goodvibes:end -->

package/templates/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Thanks for wanting to improve this project. Every contribution helps, no matter how small.
+
+## How to contribute
+
+1. **Fork this repository on GitHub.** Click the "Fork" button in the top-right corner of the repository page. This creates your own copy of the project under your GitHub account.
+
+2. **Clone your fork.** Download your copy to your computer:
+
+   ```
+   git clone https://github.com/YOUR_GITHUB_USERNAME/PROJECT_NAME.git
+   ```
+
+   Replace `YOUR_GITHUB_USERNAME` with your actual GitHub username and `PROJECT_NAME` with the actual repository name. You can find the exact URL by clicking the green "Code" button on your fork's GitHub page.
+
+3. **Create a branch for your change.** A branch is a separate workspace that keeps your work isolated from the main codebase:
+
+   ```
+   git checkout -b my-fix
+   ```
+
+   Give the branch a short name that describes what you are changing — for example, `fix-login-bug` or `add-dark-mode`.
+
+4. **Make your changes.** Edit the files you want to change and save them.
+
+5. **Stage and commit your changes.** This saves a snapshot of your work with a message:
+
+   ```
+   git add -A
+   git commit -m "Describe what you changed"
+   ```
+
+   Write the commit message in the present tense: "Fix typo in README" not "fixed stuff".
+
+6. **Push your branch to GitHub.** This sends your local branch to your fork:
+
+   ```
+   git push origin my-fix
+   ```
+
+   Replace `my-fix` with your actual branch name.
+
+7. **Open a pull request.** Go to your fork on GitHub. You will usually see a banner at the top saying "You recently pushed a branch — open a pull request." Click the button. If the banner is not there, click the "Pull requests" tab, then "New pull request", and select your branch.
+
+## What makes a good pull request
+
+- **One change per pull request.** Smaller PRs are easier to review and easier to revert if something goes wrong.
+- **Write a clear title** that says what the PR does, not just what files you changed. Example: "Fix login page crash on empty password" is better than "Update auth.js".
+- **If the change is large, open an issue first** to discuss your approach before writing the code. This saves time for everyone.
+- **All automated checks must pass** before your PR will be reviewed. If checks fail, look at the error output and fix the issue.
+
+## Questions
+
+Open a GitHub issue if you have a question or want to discuss an idea before starting work.

package/templates/JOURNAL.md

@@ -0,0 +1,32 @@
+# Engineering Journal
+
+Log what you built, what you learned, and what you want to revisit.
+
+## Entry template
+
+```
+## YYYY-MM-DD — [one sentence describing what you worked on]
+
+**What I did:** [2-3 sentences describing the work completed]
+
+**What I learned:** [anything surprising, confusing, or worth remembering]
+
+**Decisions made:** [choices you made and why — helps you explain them later]
+
+**Next time:** [what you would do differently, or what to do next session]
+```
+
+## Example entry
+
+## 2026-06-23 — Added user login page
+
+**What I did:** Created a login form with email and password fields. Wired it to the
+existing /api/auth/login endpoint. Added basic error messages for wrong credentials.
+
+**What I learned:** The fetch API in the browser does not send cookies by default —
+you need `credentials: 'include'` to make session cookies work cross-origin.
+
+**Decisions made:** Used a simple fetch call instead of a library because the project
+only has one API call so far. Will revisit if the codebase grows.
+
+**Next time:** Add a loading spinner while the login request is in flight.

package/templates/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you discover a security vulnerability, please do not open a public GitHub issue. Public issues are visible to everyone, which gives attackers an opportunity to exploit the problem before it is fixed.
+
+Instead, report it privately using GitHub's private vulnerability reporting feature: go to the Security tab of this repository, click "Report a vulnerability", and fill out the form. Your report will only be visible to the repository maintainers.
+
+## Response
+
+- We will acknowledge your report within 48 hours.
+- We will aim to release a fix within 30 days of confirmation, depending on severity.
+
+## Scope
+
+This security policy applies to the code in this repository. It does not apply to issues in third-party dependencies — please report those to the upstream project.