@ifi/oh-pi-skills 0.4.4 → 0.5.0

package/skills/devenv/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: devenv
+description: Use devenv as the task runner and development environment when devenv.nix is present in the
+  project. Run scripts via `devenv test` to enter the shell, or `devenv shell <command>` when
+  commands aren't available outside the shell. Prefer devenv scripts over ad-hoc commands. Use when
+  devenv.nix exists, or when the user asks about devenv setup, scripts, processes, or Nix-based
+  dev environments.
+---
+
+# devenv Skill
+
+## Activation
+
+Load this skill when `devenv.nix` exists in the project root, or when the user mentions devenv,
+Nix shells, or project task runners.
+
+## Quick start
+
+```bash
+# Enter the development shell (sets up PATH, env, git hooks)
+devenv test
+
+# Run a one-off command inside the shell
+devenv shell <command>
+
+# Run a named script
+devenv shell <script-name>
+# Example: devenv shell lint:all
+```
+
+## Core rules
+
+1. **Prefer devenv scripts over raw commands.** When a `scripts` block exists in `devenv.nix`,
+   always use the script name instead of the underlying command.
+
+   ```bash
+   # ✅ Preferred
+   devenv shell lint:all
+   devenv shell test:all
+
+   # ❌ Avoid
+   cargo clippy --workspace --all-features -- -D warnings
+   pnpm test
+   ```
+
+2. **Use `devenv shell <command>` when direct commands fail.** If `pnpm`, `cargo`, or other
+   project tools are not on PATH, prefix with `devenv shell`:
+
+   ```bash
+   devenv shell pnpm install
+   devenv shell cargo build --workspace
+   ```
+
+3. **Use `devenv test` to enter the shell** for interactive work or to verify the environment
+   is correctly set up.
+
+4. **Check `devenv.nix` scripts before inventing commands.** Always read the `scripts` block to
+   find existing task names before running raw commands.
+
+## Common patterns
+
+### Running project tasks
+
+```bash
+devenv shell build:all       # Build everything
+devenv shell test:all        # Run all tests
+devenv shell lint:all        # Run all lints
+devenv shell fix:all         # Fix all autofixable problems
+devenv shell docs:check      # Check documentation
+devenv shell docs:update     # Update shared docs
+```
+
+### Managing the environment
+
+```bash
+devenv test                  # Enter the shell (sets up env + hooks)
+devenv update                # Update flake inputs
+devenv gc                    # Garbage collect old generations
+```
+
+### Running processes
+
+```bash
+devenv up                    # Start all processes (postgres, redis, etc.)
+devenv processes status      # Check running processes
+```
+
+## When scripts aren't on PATH
+
+Some devenv configurations set `enterShell` to add scripts to PATH via:
+
+```nix
+enterShell = ''
+  export PATH="$DEVENV_ROOT/scripts:$PATH"
+'';
+```
+
+In those cases, scripts may be available directly inside `devenv test`. Outside the shell, always
+use `devenv shell <script-name>`.
+
+## Script naming conventions
+
+The user's preferred `devenv.nix` layout uses colon-separated namespaced scripts:
+
+- `build:*` — build tasks
+- `test:*` — test tasks
+- `lint:*` — lint and check tasks
+- `fix:*` — autofix tasks
+- `install:*` — dependency installation tasks
+- `update:*` — update tasks
+- `docs:*` — documentation tasks
+- `coverage:*` — coverage tasks
+- `snapshot:*` — snapshot update/review tasks
+- `setup:*` — editor/tool setup tasks
+- `clean:*` — cleanup tasks
+- `deny:check` — security/license checks
+- `publish:check` — publication dry-run checks
+
+## See also
+
+For the recommended `devenv.nix` layout, script structure, and git-hooks configuration, see
+[REFERENCE.md](REFERENCE.md).

package/skills/flutter-serverpod-mvp/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: flutter-serverpod-mvp
-description:
-  Scaffold and evolve full-stack Flutter + Serverpod MVPs using devenv, Riverpod + Hooks,
+description: Scaffold and evolve full-stack Flutter + Serverpod MVPs using devenv, Riverpod + Hooks,
   strict i18n, and GoRouter shell routing patterns inspired by OpenBudget.
 ---
 

package/skills/git-workflow/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: git-workflow
-description:
-  Git workflow assistant for branching, commits, PRs, and conflict resolution. Use when user asks
+description: Git workflow assistant for branching, commits, PRs, and conflict resolution. Use when user asks
   about git strategy, branch management, or PR workflow.
 ---
 
@@ -9,6 +8,83 @@ description:
 
 Help with Git operations and workflow best practices.
 
+## Core Principles
+
+### 1. Commit early and often
+
+**Make small, frequent commits rather than accumulating large batches of changes.**
+
+- Commit after every logical unit of work — even if it's just "wip: explore approach" or "wip: add failing test"
+- A commit is cheap; losing work is expensive
+- Small commits make reviews easier, bisection faster, and rollbacks safer
+- Don't wait until everything is "perfect" — a messy commit history can be cleaned later with interactive rebase
+- Prefer `git commit -m "wip: <description>"` over leaving work uncommitted for long stretches
+
+### 2. Use `git stash` instead of discarding
+
+**When you need to clear or reset uncommitted work, never just delete it — stash it with an explanation.**
+
+- Use `git stash push -m "<reason>: <description>"` to preserve work and record _why_ it was stashed
+- The stash remains in Git history and can be recovered via `git stash list` or `git reflog`
+- This protects against mistakes, dead ends that turn out to be useful later, or context lost during interruptions
+- If you later decide the stashed work is truly worthless — only then drop it explicitly with `git stash drop <stash>`
+- Explaining the stash in the message also helps future-you (or the next agent) understand what was happening
+
+Example:
+
+```bash
+# Bad: work is just gone
+rm -rf changed-files/
+git checkout -- .
+
+# Good: work is preserved with context
+git stash push -m "pivot: abandoning approach A for approach B after benchmark regression"
+git stash push -m "interrupted: switching to urgent bugfix PR #123"
+```
+
+### 3. Use worktrees for new work
+
+**Start new work in a fresh worktree rather than working directly on `main` or the current branch.**
+
+- Create a worktree for every distinct task or feature: `git worktree add -b feat/description ../worktrees/feat-description`
+- Keeps `main` clean and available for quick reference, hotfixes, or parallel reviews
+- Eliminates risk of accidentally committing work-in-progress to the trunk
+- Makes it safe to run tests, builds, and linting in isolation without polluting the main checkout
+- When done, remove the worktree: `git worktree remove <path>` — the branch remains for PR/merge
+- If the repo has the oh-pi worktree extension, prefer `/worktree create --purpose "..."`
+
+### 4. Clean up history before sharing
+
+**Never merge or push to `origin` while `wip:` commits remain in the stack, unless the user explicitly says otherwise.**
+
+- WIP commits are for _local_ iteration only — they are checkpoints, not publication-ready units
+- Before pushing or opening a PR, restructure history so every commit is a logical, self-contained unit of work
+- Each commit should tell a clear story: what changed, why it changed, and ideally be independently buildable/testable
+- Squash related `wip:` commits using interactive rebase: `git rebase -i main`
+- Rename `wip:` commits to proper Conventional Commit messages that describe the final intent
+- If a commit cannot stand on its own (e.g. "wip: broken test"), squash it into the commit that makes it pass
+- Only ever push `wip:` commits to `origin` if the user explicitly requests it (e.g. "just push what I have")
+
+Example — cleaning up before a PR:
+
+```bash
+# Check what's in the stack
+git log --oneline main..HEAD
+
+# If there are wip: commits, restructure
+git rebase -i main
+#   pick    feat(widget): add new rendering pipeline
+#   squash  wip: failing test for edge case
+#   squash  wip: fix off-by-one in renderer
+#   pick    perf(widget): cache computed layout
+#   drop    wip: try alternative approach (abandoned)
+
+# Push the cleaned branch
+git push origin feat/widget-rendering
+```
+
+See also [Core Principle #1: Commit early and often](#1-commit-early-and-often) — commit freely with `wip:` during development, but clean up before sharing.
+
 ## Capabilities
 
 ### Branch Strategy
@@ -26,9 +102,44 @@ Recommend branching strategy based on project:
 - **Team**: main + develop + feature/fix branches
 - **Release**: GitFlow (main/develop/release/hotfix)
 
+### Worktree-aware workflow
+
+When the repository uses git worktrees, do not assume the current checkout is the main repo root.
+First establish:
+
+```bash
+git rev-parse --show-toplevel
+git rev-parse --git-common-dir
+git worktree list --porcelain
+```
+
+**Prefer worktrees for all new work.** See [Core Principle #3: Use worktrees for new work](#3-use-worktrees-for-new-work).
+
+If the oh-pi worktree extension is available, prefer:
+
+- `/worktree status` — show the current worktree, canonical repo root, and pi ownership metadata
+- `/worktree list` — show all repo worktrees and which ones are pi-owned vs external/manual
+
+For pi-owned worktrees:
+
+- always record a human-readable purpose when creating one
+- preserve the owner/session metadata so cleanup decisions stay explainable
+- only clean up pi-owned worktrees by default
+- do **not** clean external/manual worktrees unless the user explicitly asks
+
+When finishing work in a worktree:
+
+1. Push the branch: `git push origin <branch>`
+2. Open a PR from the worktree branch
+3. Remove the worktree after merge: `git worktree remove <path>`
+
 ### Commit Messages
 
-Follow Conventional Commits:
+Follow Conventional Commits
+
+Small commits are better than perfect commits. See [Core Principle #1: Commit early and often](#1-commit-early-and-often).
+
+Use these prefixes:
 
 ```
 feat(scope): add new feature
@@ -39,6 +150,22 @@ test(scope): add/update tests
 chore(scope): maintenance tasks
 ```
 
+For work-in-progress commits (which are encouraged!), use `wip:` prefix or `chore(wip):`:
+
+```bash
+git commit -am "wip: explore trie-based approach for tokenization"
+git commit -am "wip: failing test for edge case in parser"
+git commit -am "wip: checkpoint before attempting refactor"
+```
+
+Clean up before opening a PR:
+
+```bash
+git rebase -i main  # squash related wip commits
+```
+
+But **never leave work uncommitted for long** — stash or commit, don't let it sit dirty.
+
 ### PR Workflow
 
 1. `git diff main --stat` — Review changes
@@ -47,10 +174,10 @@ chore(scope): maintenance tasks
 
 ### PR link in summaries
 
-When a PR has been opened, **always include the full GitHub PR URL** in any summary or status
-update you provide. This makes it easy for the user to click through to the PR directly.
+When a PR has been opened, **always include the full GitHub PR URL** in any summary or status update you provide. This makes it easy for the user to click through to the PR directly.
 
 Example summary format:
+
 ```
 PR: https://github.com/owner/repo/pull/42
 ```
@@ -61,13 +188,17 @@ Use `gh pr view --json url --jq .url` to retrieve the URL if you do not already
 
 When **the agent** runs `git` or `gh`, avoid opening an interactive editor or prompt.
 
-- For `git rebase --continue`, do **not** rely on `--no-edit` — `git rebase --continue` does not support it.
-  Use one of these instead:
-  ```bash
-  GIT_EDITOR=true git rebase --continue
-  # or
-  git -c core.editor=true rebase --continue
-  ```
+A lot of Git entrypoints use different editor config keys, so avoid surprises by disabling both:
+
+- `core.editor` / `GIT_EDITOR` (commit, merge, tag message editing)
+- `sequence.editor` / `GIT_SEQUENCE_EDITOR` (interactive rebase todo-list editing)
+
+Use this pattern for non-interactive flows:
+
+```bash
+GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true git -c core.editor=true -c sequence.editor=true rebase --continue
+```
+
 - For commits, always pass the message on the command line:
   ```bash
   git commit -m "fix(scope): message"
@@ -76,7 +207,7 @@ When **the agent** runs `git` or `gh`, avoid opening an interactive editor or pr
   ```bash
   git merge --no-edit
   ```
-- For any other git command that could open an editor, set `GIT_EDITOR=true` for that invocation.
+- For any other git command that could open an editor, set `GIT_EDITOR=true` and `GIT_SEQUENCE_EDITOR=true` (plus `-c core.editor=true -c sequence.editor=true`) for that invocation.
 - For GitHub CLI commands, disable terminal prompts and provide all required fields explicitly:
   ```bash
   GH_PROMPT_DISABLED=1 gh pr create --title "..." --body "..."
@@ -98,5 +229,5 @@ Guide through `git rebase -i` for cleaning up history before PR.
 If the agent is resolving conflicts during a rebase, continue with a non-interactive command such as:
 
 ```bash
-GIT_EDITOR=true git rebase --continue
+GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true git -c core.editor=true -c sequence.editor=true rebase --continue
 ```

package/skills/glassmorphism/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: glassmorphism
-description:
-  Glassmorphism design system skill. Use when building frosted-glass UI components with blur,
+description: Glassmorphism design system skill. Use when building frosted-glass UI components with blur,
   transparency, and layered depth effects.
 version: 1.0.0
 tags: [design, css, ui, glassmorphism]
@@ -26,12 +25,12 @@ Use CSS custom properties from `tokens.css` for consistent theming:
 @import "references/tokens.css";
 
 .glass-card {
-  background: var(--glass-bg);
-  backdrop-filter: var(--glass-blur);
-  -webkit-backdrop-filter: var(--glass-blur);
-  border: var(--glass-border);
-  border-radius: var(--glass-radius);
-  box-shadow: var(--glass-shadow);
+	background: var(--glass-bg);
+	backdrop-filter: var(--glass-blur);
+	-webkit-backdrop-filter: var(--glass-blur);
+	border: var(--glass-border);
+	border-radius: var(--glass-radius);
+	box-shadow: var(--glass-shadow);
 }
 ```
 
@@ -41,13 +40,13 @@ Use CSS custom properties from `tokens.css` for consistent theming:
 
 ```css
 .glass-card {
-  background: var(--glass-bg);
-  backdrop-filter: var(--glass-blur);
-  -webkit-backdrop-filter: var(--glass-blur);
-  border: var(--glass-border);
-  border-radius: var(--glass-radius);
-  box-shadow: var(--glass-shadow);
-  padding: 1.5rem;
+	background: var(--glass-bg);
+	backdrop-filter: var(--glass-blur);
+	-webkit-backdrop-filter: var(--glass-blur);
+	border: var(--glass-border);
+	border-radius: var(--glass-radius);
+	box-shadow: var(--glass-shadow);
+	padding: 1.5rem;
 }
 ```
 
@@ -55,14 +54,14 @@ Use CSS custom properties from `tokens.css` for consistent theming:
 
 ```css
 .glass-nav {
-  background: var(--glass-bg-heavy);
-  backdrop-filter: var(--glass-blur-strong);
-  -webkit-backdrop-filter: var(--glass-blur-strong);
-  border-bottom: var(--glass-border);
-  box-shadow: var(--glass-shadow);
-  position: sticky;
-  top: 0;
-  z-index: 100;
+	background: var(--glass-bg-heavy);
+	backdrop-filter: var(--glass-blur-strong);
+	-webkit-backdrop-filter: var(--glass-blur-strong);
+	border-bottom: var(--glass-border);
+	box-shadow: var(--glass-shadow);
+	position: sticky;
+	top: 0;
+	z-index: 100;
 }
 ```
 
@@ -70,16 +69,16 @@ Use CSS custom properties from `tokens.css` for consistent theming:
 
 ```css
 .glass-modal-backdrop {
-  background: rgba(0, 0, 0, 0.4);
-  backdrop-filter: blur(4px);
+	background: rgba(0, 0, 0, 0.4);
+	backdrop-filter: blur(4px);
 }
 .glass-modal {
-  background: var(--glass-bg-heavy);
-  backdrop-filter: var(--glass-blur-strong);
-  -webkit-backdrop-filter: var(--glass-blur-strong);
-  border: var(--glass-border);
-  border-radius: var(--glass-radius-lg);
-  box-shadow: var(--glass-shadow-elevated);
+	background: var(--glass-bg-heavy);
+	backdrop-filter: var(--glass-blur-strong);
+	-webkit-backdrop-filter: var(--glass-blur-strong);
+	border: var(--glass-border);
+	border-radius: var(--glass-radius-lg);
+	box-shadow: var(--glass-shadow-elevated);
 }
 ```
 
@@ -87,15 +86,15 @@ Use CSS custom properties from `tokens.css` for consistent theming:
 
 ```css
 .glass-btn {
-  background: var(--glass-bg-light);
-  backdrop-filter: var(--glass-blur-light);
-  -webkit-backdrop-filter: var(--glass-blur-light);
-  border: var(--glass-border);
-  border-radius: var(--glass-radius);
-  transition: background 0.2s;
+	background: var(--glass-bg-light);
+	backdrop-filter: var(--glass-blur-light);
+	-webkit-backdrop-filter: var(--glass-blur-light);
+	border: var(--glass-border);
+	border-radius: var(--glass-radius);
+	transition: background 0.2s;
 }
 .glass-btn:hover {
-  background: var(--glass-bg);
+	background: var(--glass-bg);
 }
 ```
 
@@ -112,13 +111,13 @@ Use CSS custom properties from `tokens.css` for consistent theming:
 
 ```css
 .glass-card {
-  background: rgba(255, 255, 255, 0.85); /* fallback */
+	background: rgba(255, 255, 255, 0.85); /* fallback */
 }
 @supports (backdrop-filter: blur(1px)) {
-  .glass-card {
-    background: var(--glass-bg);
-    backdrop-filter: var(--glass-blur);
-  }
+	.glass-card {
+		background: var(--glass-bg);
+		backdrop-filter: var(--glass-blur);
+	}
 }
 ```
 
@@ -133,15 +132,15 @@ Use CSS custom properties from `tokens.css` for consistent theming:
 
 ```css
 @media (prefers-reduced-transparency: reduce) {
-  .glass-card {
-    background: rgba(255, 255, 255, 0.92);
-    backdrop-filter: none;
-  }
+	.glass-card {
+		background: rgba(255, 255, 255, 0.92);
+		backdrop-filter: none;
+	}
 }
 @media (prefers-contrast: more) {
-  .glass-card {
-    background: rgba(255, 255, 255, 0.85);
-    border: 1px solid rgba(0, 0, 0, 0.3);
-  }
+	.glass-card {
+		background: rgba(255, 255, 255, 0.85);
+		border: 1px solid rgba(0, 0, 0, 0.3);
+	}
 }
 ```

package/skills/glassmorphism/references/tokens.css

@@ -1,32 +1,32 @@
 :root {
-  /* Backgrounds */
-  --glass-bg-light: rgba(255, 255, 255, 0.08);
-  --glass-bg: rgba(255, 255, 255, 0.15);
-  --glass-bg-heavy: rgba(255, 255, 255, 0.25);
+	/* Backgrounds */
+	--glass-bg-light: rgba(255, 255, 255, 0.08);
+	--glass-bg: rgba(255, 255, 255, 0.15);
+	--glass-bg-heavy: rgba(255, 255, 255, 0.25);
 
-  /* Blur */
-  --glass-blur-light: blur(8px);
-  --glass-blur: blur(16px);
-  --glass-blur-strong: blur(32px);
+	/* Blur */
+	--glass-blur-light: blur(8px);
+	--glass-blur: blur(16px);
+	--glass-blur-strong: blur(32px);
 
-  /* Border */
-  --glass-border: 1px solid rgba(255, 255, 255, 0.18);
+	/* Border */
+	--glass-border: 1px solid rgba(255, 255, 255, 0.18);
 
-  /* Radius */
-  --glass-radius: 12px;
-  --glass-radius-lg: 20px;
+	/* Radius */
+	--glass-radius: 12px;
+	--glass-radius-lg: 20px;
 
-  /* Shadow */
-  --glass-shadow: 0 4px 30px rgba(0, 0, 0, 0.1);
-  --glass-shadow-elevated: 0 8px 40px rgba(0, 0, 0, 0.15);
+	/* Shadow */
+	--glass-shadow: 0 4px 30px rgba(0, 0, 0, 0.1);
+	--glass-shadow-elevated: 0 8px 40px rgba(0, 0, 0, 0.15);
 }
 
 /* Dark theme overrides */
 [data-theme="dark"] {
-  --glass-bg-light: rgba(255, 255, 255, 0.04);
-  --glass-bg: rgba(255, 255, 255, 0.08);
-  --glass-bg-heavy: rgba(255, 255, 255, 0.14);
-  --glass-border: 1px solid rgba(255, 255, 255, 0.12);
-  --glass-shadow: 0 4px 30px rgba(0, 0, 0, 0.3);
-  --glass-shadow-elevated: 0 8px 40px rgba(0, 0, 0, 0.4);
+	--glass-bg-light: rgba(255, 255, 255, 0.04);
+	--glass-bg: rgba(255, 255, 255, 0.08);
+	--glass-bg-heavy: rgba(255, 255, 255, 0.14);
+	--glass-border: 1px solid rgba(255, 255, 255, 0.12);
+	--glass-shadow: 0 4px 30px rgba(0, 0, 0, 0.3);
+	--glass-shadow-elevated: 0 8px 40px rgba(0, 0, 0, 0.4);
 }