feat: reorganize skills with canonical agents/ locations and symlinks

- Symlink dotfiles/claude/CLAUDE.md -> ../agents/AGENTS.md - Move global skills to dotfiles/agents/skills/ as canonical location (hackage-release, org-agenda-api-production, release) - Add new taffybar-ecosystem-release skill documenting the taffybar package dependency graph and release propagation workflow - ~/.claude/skills/ entries are now symlinks to canonical locations - email-cleanup and weekly-scheduling moved to ~/org/agents/skills/ - Removed stale debug-video-processing symlink Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-10 19:40:52 -08:00
parent 73c766e828
commit 781b5297ad
5 changed files with 325 additions and 41 deletions
--- a/dotfiles/agents/skills/hackage-release/SKILL.md
+++ b/dotfiles/agents/skills/hackage-release/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: hackage-release
+description: Use when user asks to release, publish, or bump version of a Haskell package to Hackage
+---
+
+# Hackage Release
+
+Bump version, build, validate, tag, push, and publish a Haskell package to Hackage.
+
+## Workflow
+
+1. **Bump version** in `package.yaml` (if using hpack) or `.cabal` file
+2. **Update ChangeLog.md** with release notes
+3. **Regenerate cabal** (if using hpack): `hpack`
+4. **Build**: `cabal build`
+5. **Check**: `cabal check` (must report zero warnings)
+6. **Create sdist**: `cabal sdist`
+7. **Commit & tag**: commit all changed files, `git tag vX.Y.Z.W`
+8. **Push**: `git push && git push --tags`
+9. **Get Hackage credentials**: `pass show hackage.haskell.org.gpg`
+   - Format: first line is password, `user:` line has username
+10. **Publish package**: `cabal upload --publish <sdist-tarball> --username=<user> --password='<pass>'`
+11. **Build & publish docs**: `cabal haddock --haddock-for-hackage` then `cabal upload --documentation --publish <docs-tarball> --username=<user> --password='<pass>'`
+
+## Version Bumping (PVP)
+
+Haskell uses the [Package Versioning Policy](https://pvp.haskell.org/) with format `A.B.C.D`:
+
+| Component | When to Bump |
+|-----------|-------------|
+| A.B (major) | Breaking API changes |
+| C (minor) | Backwards-compatible new features |
+| D (patch) | Bug fixes, non-API changes |
+
+## Nix-Based Projects
+
+If the project uses a Nix flake, wrap cabal commands with `nix develop`:
+
+```bash
+nix develop --command cabal build
+nix develop --command cabal check
+nix develop --command hpack package.yaml
+```
+
+Prefer `nix develop` (flake) over `nix-shell` (legacy) to avoid ABI mismatches.
+
+## PVP Dependency Bounds
+
+Hackage warns about:
+- **Missing upper bounds**: Every dependency should have an upper bound (e.g., `text >= 1.2 && < 2.2`)
+- **Trailing zeros in upper bounds**: Use `< 2` not `< 2.0.0`; use `< 0.4` not `< 0.4.0.0`
+
+Run `cabal check` to verify zero warnings before releasing.
+
+## Checklist
+
+- [ ] Version bumped in package.yaml / .cabal
+- [ ] ChangeLog.md updated
+- [ ] Cabal file regenerated (if hpack)
+- [ ] `cabal build` succeeds
+- [ ] `cabal check` reports no errors or warnings
+- [ ] Changes committed and tagged
+- [ ] Pushed to remote with tags
+- [ ] Package published to Hackage
+- [ ] Docs published to Hackage
--- a/dotfiles/agents/skills/org-agenda-api-production/SKILL.md
+++ b/dotfiles/agents/skills/org-agenda-api-production/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: org-agenda-api-production
+description: Use when investigating production org-agenda-api state, testing endpoints, or debugging production issues
+---
+
+# org-agenda-api Production Access
+
+## Overview
+
+Access the production org-agenda-api instance at https://colonelpanic-org-agenda.fly.dev/ for debugging, testing, or verification.
+
+## Credentials
+
+Get credentials from pass:
+```bash
+pass show colonelpanic-org-agenda.fly.dev
+```
+
+Format:
+- Line 1: password
+- `user:` field: username
+
+## Quick Access with just
+
+The project includes a justfile with pre-configured commands:
+
+```bash
+# Authenticated curl to any endpoint
+just prod /health
+just prod /get-all-todos
+just prod "/agenda?span=week"
+
+# Common shortcuts
+just health      # Health check
+just version     # API version
+just todos       # All todos
+just today       # Today's agenda
+just agenda      # Day agenda (or: just agenda week)
+just templates   # Capture templates
+just metadata    # Full metadata
+```
+
+## Manual curl
+
+```bash
+curl -s -u "$(pass show colonelpanic-org-agenda.fly.dev | grep '^user:' | cut -d' ' -f2):$(pass show colonelpanic-org-agenda.fly.dev | head -1)" \
+  https://colonelpanic-org-agenda.fly.dev/health | jq
+```
+
+## Key Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| /health | GET | Health check |
+| /version | GET | API version |
+| /get-all-todos | GET | All TODO items |
+| /agenda | GET | Agenda (span=day\|week) |
+| /capture | POST | Create entry |
+| /update | POST | Update heading |
+| /complete | POST | Complete item |
+| /delete | POST | Delete heading |
--- a/dotfiles/agents/skills/release/SKILL.md
+++ b/dotfiles/agents/skills/release/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: release
+description: Use when user asks to release, publish, bump version, or prepare a new version for deployment
+---
+
+# Release
+
+Validate, format, bump version, and tag for release.
+
+## Workflow
+
+1. **Validate** - Run project's validation command
+2. **Fix formatting** - Auto-fix prettier/formatting issues if any
+3. **Bump version** - Ask user for bump type, update package.json
+4. **Commit & tag** - Commit version bump, create git tag
+5. **Optionally push** - Ask if user wants to push
+
+## Commands
+
+```bash
+# 1. Validate
+yarn validate  # or: npm run validate
+
+# 2. Fix formatting if needed
+yarn prettier:fix  # or: npm run prettier:fix
+
+# 3. Bump version (edit package.json)
+# patch: 1.2.3 → 1.2.4
+# minor: 1.2.3 → 1.3.0
+# major: 1.2.3 → 2.0.0
+
+# 4. Commit and tag
+git add package.json
+git commit -m "chore: bump version to X.Y.Z"
+git tag vX.Y.Z
+
+# 5. Push (if requested)
+git push && git push --tags
+```
+
+## Quick Reference
+
+| Bump Type | When to Use |
+|-----------|-------------|
+| patch | Bug fixes, small changes |
+| minor | New features, backwards compatible |
+| major | Breaking changes |
+
+## Before Release Checklist
+
+- [ ] All tests pass
+- [ ] No lint errors
+- [ ] Formatting is clean
+- [ ] Changes are committed
--- a/dotfiles/agents/skills/taffybar-ecosystem-release/SKILL.md
+++ b/dotfiles/agents/skills/taffybar-ecosystem-release/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: taffybar-ecosystem-release
+description: Use when releasing, version-bumping, or propagating changes across taffybar GitHub org packages (taffybar, gtk-sni-tray, gtk-strut, status-notifier-item, dbus-menu, dbus-hslogger)
+---
+
+# Taffybar Ecosystem Release
+
+Release and propagate changes across the taffybar Haskell package ecosystem.
+
+## Package Dependency Graph
+
+```
+imalison-taffybar  (user config — ~/.config/taffybar/)
+└── taffybar  (main library — ~/.config/taffybar/taffybar/)
+    ├── gtk-sni-tray
+    │   ├── dbus-menu
+    │   ├── gtk-strut
+    │   └── status-notifier-item
+    ├── dbus-menu
+    ├── gtk-strut
+    ├── status-notifier-item
+    └── dbus-hslogger
+```
+
+**Leaf packages** (no ecosystem deps): `gtk-strut`, `status-notifier-item`, `dbus-hslogger`, `dbus-menu`
+**Mid-level**: `gtk-sni-tray` (depends on dbus-menu, gtk-strut, status-notifier-item)
+**Top-level lib**: `taffybar` (depends on all above)
+**User config**: `imalison-taffybar` (depends on taffybar + gtk-sni-tray + gtk-strut)
+
+## Repositories & Local Checkouts
+
+| Package | GitHub | Local Checkout |
+|---------|--------|---------------|
+| taffybar | taffybar/taffybar | `~/.config/taffybar/taffybar/` |
+| gtk-sni-tray | taffybar/gtk-sni-tray | `~/Projects/gtk-sni-tray/` |
+| gtk-strut | taffybar/gtk-strut | `~/Projects/gtk-strut/` |
+| status-notifier-item | taffybar/status-notifier-item | `~/Projects/status-notifier-item/` |
+| dbus-menu | taffybar/dbus-menu | `~/Projects/dbus-menu/` |
+| dbus-hslogger | IvanMalison/dbus-hslogger | `~/Projects/dbus-hslogger/` |
+| imalison-taffybar | (dotfiles repo) | `~/.config/taffybar/` |
+
+## Release Order (Bottom-Up)
+
+Always release leaf packages first, then dependents. Changes propagate **upward**.
+
+### 1. Release the Changed Leaf Package
+
+Use the `hackage-release` skill for the Hackage publish workflow. In the local checkout (`~/Projects/<pkg>/`):
+
+1. Bump version in `.cabal` file (PVP: A.B.C.D)
+2. Update ChangeLog.md
+3. `cabal build && cabal check`
+4. `cabal sdist`
+5. Commit, tag `vX.Y.Z.W`, push with tags
+6. Publish to Hackage (see hackage-release skill for credentials)
+7. Publish docs
+
+### 2. Update Dependents' Version Bounds
+
+For each package that depends on the one you just released, update the dependency bound in its `.cabal` file. For example, if you bumped `gtk-strut` to 0.1.5.0:
+
+- In `gtk-sni-tray.cabal`: update `gtk-strut >= 0.1.5 && < 0.2`
+- In `taffybar.cabal`: update `gtk-strut >= 0.1.5 && < 0.2`
+
+Then release those packages if needed (repeat from step 1).
+
+### 3. Update Nix Flake Inputs
+
+After pushing changes to GitHub, update flake.lock files that reference the changed packages:
+
+**taffybar's flake** (`~/.config/taffybar/taffybar/`):
+```bash
+cd ~/.config/taffybar/taffybar
+nix flake update gtk-strut  # or whichever input changed
+```
+
+**imalison-taffybar's flake** (`~/.config/taffybar/`):
+```bash
+cd ~/.config/taffybar
+nix flake update gtk-strut  # update the direct input
+nix flake update taffybar   # if taffybar itself changed
+```
+
+### 4. Rebuild and Test
+
+```bash
+cd ~/.config/taffybar
+nix develop --command cabal build
+```
+
+Or for a full NixOS rebuild:
+```bash
+cd ~/dotfiles/nixos && just switch
+```
+
+## Flake Input Architecture
+
+**taffybar's flake.nix** pulls all ecosystem deps as `flake = false` inputs from GitHub and builds them via `callCabal2nix` through a Nix overlay system.
+
+**imalison-taffybar's flake.nix** re-declares the same inputs as proper flake inputs (where available) and uses `inputs.X.follows` to ensure taffybar uses the same versions:
+
+```
+gtk-sni-tray.inputs.gtk-strut.follows = "gtk-strut"
+gtk-sni-tray.inputs.status-notifier-item.follows = "status-notifier-item"
+gtk-sni-tray.inputs.dbus-menu.follows = "dbus-menu"
+taffybar.inputs.gtk-sni-tray.follows = "gtk-sni-tray"
+...
+```
+
+This means updating a leaf input in the imalison config flake automatically threads it through to taffybar and gtk-sni-tray.
+
+## Common Scenarios
+
+### Changed a leaf package (e.g. status-notifier-item)
+
+1. Make changes in `~/Projects/status-notifier-item/`
+2. Release to Hackage if publishing
+3. Push to GitHub
+4. `cd ~/.config/taffybar && nix flake update status-notifier-item`
+5. Rebuild
+
+### Changed taffybar itself
+
+1. Make changes in `~/.config/taffybar/taffybar/`
+2. Push to GitHub (or just rebuild — imalison config uses `path:` input)
+3. `cd ~/.config/taffybar && nix flake update taffybar`
+4. Rebuild
+
+### Changed gtk-sni-tray (mid-level)
+
+1. Make changes in `~/Projects/gtk-sni-tray/`
+2. If a leaf dep also changed, update bounds in `gtk-sni-tray.cabal`
+3. Push to GitHub
+4. `cd ~/.config/taffybar && nix flake update gtk-sni-tray`
+5. Rebuild
+
+### Full ecosystem release (all packages)
+
+Release in this exact order:
+1. `gtk-strut`, `status-notifier-item`, `dbus-hslogger`, `dbus-menu` (leaves, parallel OK)
+2. `gtk-sni-tray` (update bounds for any leaf changes first)
+3. `taffybar` (update bounds for all changes)
+4. Update all flake inputs in imalison config
+5. Rebuild