@xynogen/pix-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# pix-skills
+
+Pi coding agent extension — skill loader tool + skills bundle.
+
+## What's included
+
+| Resource | Type | Description |
+|---|---|---|
+| `read_skill` | tool | Load a bundled skill's full instructions by name. `name="list"` lists all skills with descriptions. |
+| `skills/` | skills | 21 bundled skills (auto-loaded by pi at startup — names + descriptions in system prompt) |
+
+## How it works
+
+Pi loads skill *descriptions* into the system prompt at startup (progressive disclosure). Full content
+only enters context when the agent calls `read_skill(name=<skill>)` — or reads the file via the `read` tool.
+
+`read_skill` is the safe version of "agent prompts itself":
+- Agent calls tool explicitly — no autonomous injection
+- Orchestrator (user or system prompt) decides when skill loading is appropriate
+- Auditable: tool call is visible in the conversation
+
+## Skills
+
+| Skill | Trigger |
+|---|---|
+| `audit` | manual |
+| `bootstrap` | manual |
+| `brainstorm` | manual |
+| `clone` | auto — git URL / `owner/repo` |
+| `commit` | manual — "commit this", "make a commit" |
+| `debug` | auto — bug / error / doesn't work |
+| `explain` | auto — explain / how does |
+| `finish` | manual |
+| `handoff` | manual |
+| `plan` | auto — plan / design / architect |
+| `readme` | manual |
+| `review` | auto — review / check / audit |
+| `runner` | manual |
+| `search` | auto — search / find / look up |
+| `standup` | manual |
+| `suggest` | auto — suggest / recommend |
+| `task` | auto — task / todo / checklist |
+| `test` | auto — test / spec / coverage |
+| `tldr` | auto — tldr / summarize |
+| `ui` | manual |
+| `verify` | auto — verify / validate / confirm |
+
+## Usage
+
+```
+# Agent lists available skills
+read_skill(name="list")
+
+# Agent loads full commit procedure before committing
+read_skill(name="commit")
+
+# User explicitly triggers a skill
+/skill:commit
+```
+
+## Install
+
+```bash
+pi install git:github.com/xynogen/pix-mono#packages/pix-skills
+```
+
+Or from the monorepo:
+
+```bash
+pi install ./packages/pix-skills
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@xynogen/pix-skills",
+	"version": "0.1.0",
+	"description": "Pi extension — agent skill loader (read_skill tool + skills bundle)",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"skills",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/index.ts"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"pix"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-skills"
+	},
+	"homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-skills#readme",
+	"bugs": {
+		"url": "https://github.com/xynogen/pix-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/skills/audit.md

@@ -0,0 +1,48 @@
+---
+name: audit
+description: Security audit, integrity check, and health scan. Use only on explicit request — "audit this", "security scan", "check for secrets", "is this safe", "find vulnerabilities".
+disable-model-invocation: true
+---
+# Audit Directive
+
+## Goal
+Surface every risk with evidence + severity. No vague warnings — each finding locatable + actionable.
+
+## Below are what agent MUST do:
+
+### Phase 1: Scan
+- **AUTO-RUN**: Run scans without confirmation unless input required.
+- **SECRETS**: Grep credential patterns — API keys, tokens, `password=`, private keys, connection strings. Check committed files AND history if asked.
+- **INTEGRITY**: Verify imports resolve, symlinks valid, cross-module refs intact.
+- **BLOAT**: Find duplicate logic, unused deps, dead files.
+- **HEALTH**: Flag outdated packages, deprecated APIs, known CVEs.
+- **INPUTS**: Check unvalidated user input → injection, path traversal, unsafe deserialization.
+
+### Phase 2: Report
+```
+## Audit Findings
+
+### 🔴 Critical
+- **[Issue]** — `file:line`
+  Evidence: [exact match/snippet]
+  Fix: [remediation step]
+
+### 🟡 Warning
+- **[Issue]** — `file:line` · Fix: [step]
+
+### 🔵 Info
+- **[Issue]** — `file:line` · Note: [context]
+
+## Summary
+[N critical, N warning, N info. Top priority: ...]
+```
+
+## Severity Rules
+- **🔴 Critical**: exposed secret, RCE, injection, auth bypass. Fix first.
+- **🟡 Warning**: outdated dep with CVE, missing input validation, weak crypto.
+- **🔵 Info**: dead code, style risk, hardening opportunity.
+
+## Red Flags — STOP
+- Reporting finding without `file:line` evidence.
+- Claiming "no issues found" without stating what scanned.
+- Auto-fixing secrets in git history (destructive — confirm with user first).

package/skills/bootstrap.md

@@ -0,0 +1,50 @@
+---
+name: bootstrap
+description: Project and tool scaffolding using authoritative docs for best practices. Use only on explicit request — "scaffold a project", "set up X", "bootstrap this", "init a new service".
+disable-model-invocation: true
+---
+# Bootstrap & Scaffolding Directive
+
+## Goal
+Produce runnable, convention-correct project skeleton. New developer clones it + runs it in five minutes.
+
+## Below are what agent MUST do:
+
+### Phase 1: Research
+- **AUTO-RUN**: Run setup commands without confirmation unless input required.
+- **RESEARCH**: Use authoritative docs for target language/framework setup. Don't guess flags — verify with `--help` or docs.
+- **CONFIRM STACK**: Language/framework/package-manager ambiguous → ask one question before scaffolding.
+
+### Phase 2: Scaffold
+- **INIT**: Run standard init (`npm init -y`, `cargo init`, `go mod init`, `uv init`, etc.).
+- **STRUCTURE**: Create standard layout — `src/`, `tests/`, `docs/`. Mirror community conventions for that ecosystem.
+- **DEPENDENCIES**: Install core libs via project manager. Pin versions.
+- **ENVIRONMENT**: Generate `.env.example`; document every required env var. Never write real secrets.
+- **TOOLING**: Set up linter, formatter, CI config matching ecosystem defaults.
+
+### Phase 3: Verify
+- Run project build/test command. Confirm clean baseline passes.
+- Confirm `README` or `.env.example` lists everything needed to run.
+
+### Phase 4: Report
+```
+## Scaffolded: [project name]
+
+**Stack:** [lang/framework/pm]
+**Layout:**
+  src/ ...
+  tests/ ...
+
+**Run it:**
+  1. [command]
+  2. [command]
+
+**Env vars required:** see `.env.example`
+**Baseline:** `[test command]` → PASS
+```
+
+## Red Flags — STOP
+- Scaffolding before confirming ambiguous stack.
+- Inventing init flags instead of checking docs.
+- Writing real secrets into `.env` (use `.env.example` with placeholders).
+- Declaring done without running baseline build/test once.

package/skills/brainstorm.md

@@ -0,0 +1,49 @@
+---
+name: brainstorm
+description: Design exploration and spec refinement before any implementation begins
+disable-model-invocation: true
+---
+# Brainstorm Directive
+
+## Hard Gate
+```
+DO NOT write code, scaffold project, or take implementation action
+until you present a design AND user approves it.
+```
+Applies to EVERY request, regardless of perceived simplicity.
+
+## Below are what agent MUST do:
+
+### Step 1: Explore Context
+- Check existing files, docs, recent git commits.
+- Understand what already exists before proposing anything new.
+
+### Step 2: Ask Clarifying Questions
+- Ask ONE question at a time. Don't overwhelm.
+- Prefer multiple-choice when possible.
+- Focus on: purpose, constraints, success criteria, edge cases.
+- Continue until you understand full scope.
+
+### Step 3: Propose 2-3 Approaches
+- Present distinct approaches with trade-offs.
+- Lead with recommended option, explain WHY.
+- Apply YAGNI ruthlessly — remove unnecessary features from all proposals.
+
+### Step 4: Present Design for Approval
+- Present design in sections scaled to complexity.
+- Cover: architecture, components, data flow, error handling, testing strategy.
+- Ask approval after each section. Revise if needed.
+
+### Step 5: Write Design Doc
+- Save validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`.
+- Commit design document to git.
+
+### Step 6: Transition to Implementation
+- Invoke `/plan` workflow to create detailed implementation plan.
+- Do NOT start coding directly. `/plan` is next step.
+
+## Key Principles
+- **One question at a time** — Don't overwhelm
+- **YAGNI ruthlessly** — Remove unnecessary features from all designs
+- **Explore alternatives** — Always propose 2-3 approaches before settling
+- **Incremental validation** — Present design, get approval before moving on

package/skills/clone.md

@@ -0,0 +1,22 @@
+---
+name: clone
+description: Clone any git repository (GitHub/GitLab/Bitbucket URL, SSH, or owner/repo shorthand) into /tmp/clones for read-only code exploration. Use proactively whenever the user provides a git URL, asks to "look at", "explore", "read", "check out", or "analyze" an external repository, or shares a github.com/gitlab.com/bitbucket.org link.
+disable-model-invocation: true
+---
+# Clone Directive
+## Below are what agent MUST do:
+- **AUTO-RUN**: Run terminal commands proactively without confirmation unless explicit input required.
+- **AUTO-INVOKE**: Trigger automatically when user message contains git URL, repo shorthand (`owner/repo`), or phrases like "clone", "look at this repo", "explore", "analyze this project", "check out <url>".
+- **INPUT**: Accept git URL (https, ssh, or `github.com/owner/repo` / `owner/repo` shorthand). Normalize shorthand → `https://github.com/owner/repo`.
+- **TARGET**: Derive repo name from URL (strip `.git`). Clone dest: `/tmp/clones/<repo-name>`.
+- **IDEMPOTENT**: `/tmp/clones/<repo-name>` exists + is git repo → `cd` in, `git fetch --all --prune`, report current branch/HEAD instead of re-cloning. Path exists but NOT git repo → abort with error.
+- **CLONE**: Use `git clone --depth=1` by default for speed. User requests full history → drop `--depth`. Always clone into `/tmp/clones/<repo-name>`.
+- **EXPLORE**: After clone/fetch, immediately:
+  - Print absolute path of clone
+  - List top-level entries (`ls -la`)
+  - Show `README.md` first 50 lines if present
+  - Detect project type (package.json, Cargo.toml, go.mod, pyproject.toml, etc.) and report stack
+  - Print `git log --oneline -5` for recent context
+- **READY**: End with one-line summary: `Repo ready at /tmp/clones/<name> — <stack> — <N> files at root`. Agent now positioned to answer follow-up questions about the code.
+- **NO MUTATIONS**: Treat clone as read-only. Do NOT commit, push, or modify files unless user explicitly requests it.
+- **CLEANUP NOTE**: `/tmp` is ephemeral (cleared on reboot). Inform user if they want persistence to move it elsewhere.

package/skills/commit.md

@@ -0,0 +1,80 @@
+---
+name: commit
+description: Split, write, and maintain Conventional-Commit-style commits. Use only on explicit request — "commit this", "make a commit", "split these changes", "amend/squash the history".
+disable-model-invocation: true
+---
+# Conventional Commit Management Directive
+
+## The Iron Law
+```
+INVOCATION IS PERMISSION. User invoked this skill → commit without asking again.
+Still forbidden: secrets, binaries, unrelated changes, trailer metadata.
+```
+
+## Below are what agent MUST do:
+
+### Phase 1: Inspect
+- **AUTO-RUN**: Run `git status` and `git diff` (staged + unstaged), then proceed straight to commit. Do NOT pause for "may I commit?" confirmation — user already asked.
+- **GITIGNORE**: Before staging, inspect untracked/generated files. Add obvious ignore candidates to `.gitignore` (build dirs, caches, logs, temp files, editor/OS junk, local env files). Re-run `git status`. Uncertain whether file should be ignored vs committed → ask user before changing `.gitignore` or staging it.
+- **GROUP**: Cluster changes by path/module and by functionality. Each cluster → one self-contained commit.
+- **GUARD**: Scan diff for secrets, binaries, debug logs, unrelated edits. Halt and report if found.
+
+### Phase 2: Validate
+
+#### 2a. Detect runner
+Scan project root for a task runner file in this priority order:
+1. `justfile` — run `just lint check`, `just format check`, `just test unit`
+2. `mise.toml` / `.mise.toml` — run `mise run lint check`, `mise run format check`, `mise run test unit`
+3. `Makefile` — run `make lint-check`, `make format-check`, `make test-unit`
+4. `Taskfile.yml` — run `task lint:check`, `task format:check`, `task test:unit`
+5. `package.json` — run `npm run lint:check`, `npm run format:check`, `npm run test:unit`
+6. `run.sh` — run `./run.sh lint check`, `./run.sh format check`, `./run.sh test unit`
+
+#### 2b. Runner or tasks missing
+If **no runner file exists** OR the runner exists but **lacks `lint`, `format`, or `test` tasks**:
+- Ask user:
+  > Runner / task(s) not found. Options:
+  > A) **Create runner + tasks now** — invoke the `runner` skill to generate missing tasks, then run them before committing.
+  > B) **Skip validation** — commit without lint/format/test (risky; recorded in commit body).
+  > C) **Abort** — stop here; user will set up runner manually.
+- If user picks A: invoke runner skill, generate the missing tasks, re-detect, then proceed with 2c.
+- If user picks B: proceed to Phase 3. Append `skip-validation: lint format test` to commit body as a reminder.
+- If user picks C: halt. Report what's missing and suggest running the `runner` skill manually.
+
+#### 2c. Run checks (in order)
+1. **Lint** (`lint check`) — static analysis. Failure → STOP, report issues, do not commit.
+2. **Format** (`format check`) — style check (dry-run). Failure → auto-run `format fix`, show diff, then re-run `format check` to confirm clean. Still failing → STOP.
+3. **Unit tests** (`test unit`) — correctness. Failure → STOP, report failing tests, do not commit.
+
+All three must be green before proceeding to Phase 3.
+
+### Phase 3: Compose
+Format: `<type>(<scope>): <subject>`
+- **type**: `feat` · `fix` · `chore` · `refactor` (also `docs`, `test`, `perf` when apt).
+- **scope**: module/area touched. Clear, lowercase.
+- **subject**: imperative, concise, no trailing period.
+
+```
+feat(auth): add token refresh on 401
+fix(parser): handle empty CUDA frame without panic
+refactor(api): extract response builder from handler
+```
+
+### Phase 4: Split & Stage
+- Stage per cluster: `git add <paths>` (or `-p` for partial hunks).
+- One commit per logical change. Never mix `feat` + unrelated `fix` in one commit.
+
+### Phase 5: Maintain (when asked)
+- Squash/amend/reorder to keep history clean. Remove WIP commits.
+- Never rewrite pushed history without explicit confirmation (irreversible for collaborators).
+
+## Authorship Rule
+- Commits authored solely by user's git config identity.
+- Do NOT add `Co-Authored-By`, `Signed-off-by`, or any trailer metadata.
+
+## Red Flags — STOP
+- Asking "should I commit?" after skill invoked — invocation already answered that.
+- Secrets, binaries, or `console.log`/`print` debug lines in diff.
+- One commit bundling unrelated changes.
+- Tests/lints not run, or failing.
+- Rewriting pushed history without confirmation.

package/skills/debug.md

@@ -0,0 +1,55 @@
+---
+name: debug
+description: Root-Cause Analysis and self-annealing procedure for error resolution
+disable-model-invocation: true
+---
+# Debug & Anneal Directive
+
+## The Iron Law
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+Phase 1 not complete → you CANNOT propose fixes.
+
+## First Principles Debugging
+Before diving into symptoms, strip problem to fundamentals:
+1. **What MUST be true** for system to work correctly? List the invariants.
+2. **Which invariant violated?** Bug lives where reality diverges from required truth.
+3. **Why violated?** Trace from violated invariant backward — ignore surface symptoms.
+4. Do NOT reason by analogy ("last time this error meant X"). Reason from mechanism ("this error means Y in state Z, which requires W to have failed").
+
+## Below are what agent MUST do:
+
+### Phase 1: Root Cause Investigation
+- **READ**: Read error messages and stack traces completely. Note line numbers, file paths, error codes.
+- **REPRODUCE**: Reproduce error consistently. Not reproducible → gather more data, do NOT guess.
+- **CHANGES**: Check recent changes (git diff, recent commits, new deps, config changes).
+- **EVIDENCE**: Multi-component systems → add diagnostic logging at each boundary BEFORE proposing fixes. Run once to gather evidence, THEN analyze.
+- **TRACE**: Trace data flow backward through call stack to find original trigger. Fix at source, not symptom.
+
+### Phase 2: Pattern Analysis
+- **EXAMPLES**: Find working examples of similar code in codebase.
+- **COMPARE**: Compare working vs broken. List every difference, however small.
+- **DEPENDENCIES**: Understand what config, environment, or assumptions code relies on.
+
+### Phase 3: Hypothesis and Testing
+- **HYPOTHESIZE**: State clearly: "I think X is root cause because Y." Write it down.
+- **TEST MINIMALLY**: Make SMALLEST possible change to test hypothesis. One variable at a time.
+- **VERIFY**: Worked? Yes → Phase 4. No → form NEW hypothesis. Do NOT stack fixes.
+
+### Phase 4: Implementation
+- **TEST FIRST**: Create failing test reproducing bug BEFORE writing fix.
+- **FIX**: Implement single, targeted fix addressing root cause. No "while I'm here" changes.
+- **VERIFY**: Confirm test passes and no regressions via `/test`.
+- **ANNEAL**: Error due to missing rules → update appropriate Directive.
+
+## Escalation Rule
+- 3+ fixes failed → **STOP**. Question the architecture. Discuss with user before more fixes. This is wrong architecture, not wrong hypothesis.
+
+## Red Flags — STOP and Return to Phase 1
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+- Each fix reveals new problem in different place

package/skills/explain.md

@@ -0,0 +1,47 @@
+---
+name: explain
+description: Technical deconstruction and logic tracing. Use when user asks "how does X work", "explain this", "walk me through", "what does this do", or needs to understand existing code/architecture before changing it.
+disable-model-invocation: true
+---
+# Explain Directive
+
+## Goal
+Make code understandable from local reading. After explaining, reader grasps intent without re-tracing codebase themselves.
+
+## Below are what agent MUST do:
+
+### Phase 1: Locate & Scope
+- **AUTO-RUN**: Run searches and reads needed without confirmation unless input required.
+- **CONTEXT**: Identify exact target — file, function, class, or concept. Quote the `file:line` under discussion.
+- **READ**: Read full target plus immediate callers and callees. Don't explain from name alone.
+
+### Phase 2: Deconstruct
+- **STRUCTURE**: Break logic into named components (inputs → transform → outputs → side effects).
+- **TRACE**: Map data flow and call chain. State where data enters, what mutates it, where it exits.
+- **RATIONALE**: Explain the *why* behind non-obvious choices. Why unknowable → say so, don't invent intent.
+- **CONTRACTS**: Note types, invariants, assumptions code relies on.
+
+### Phase 3: Report
+Use this structure:
+```
+## What it does
+[One sentence.]
+
+## How it works
+1. [Step] — `file:line`
+2. [Step] — `file:line`
+
+## Data flow
+[input] → [transform] → [output/side-effect]
+
+## Why this way
+[Design rationale, or "rationale not documented" if unknown.]
+
+## Gotchas
+[Non-obvious behavior, edge cases, hidden dependencies.]
+```
+
+## Red Flags — STOP
+- Explaining from function name without reading its body.
+- Inventing rationale not supported by code or comments.
+- Describing *what* a line does when self-evident — explain *why* instead.

package/skills/finish.md

@@ -0,0 +1,78 @@
+---
+name: finish
+description: Structured branch completion — verify, decide, and clean up when implementation is done
+disable-model-invocation: true
+---
+# Finish Directive
+
+## Overview
+Guide completion of dev work by verifying tests + presenting clear options for the branch.
+
+**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+
+## Below are what agent MUST do:
+
+### Step 1: Verify Tests
+Run full test suite BEFORE presenting any options.
+```bash
+# Use the project's test command, e.g.:
+pytest / npm test / go test ./... / cargo test
+```
+- Tests **fail** → Show failures. Do NOT proceed to Step 2. Fix first.
+- Tests **pass** → Continue.
+
+### Step 2: Present Options
+Present exactly these 4 options — no more, no less:
+```
+Implementation complete. All tests pass. What would you like to do?
+
+1. Merge into <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (handle it later)
+4. Discard this work
+
+Which option?
+```
+
+### Step 3: Execute Choice
+
+**Option 1 — Merge locally:**
+```bash
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+<run tests again on merged result>
+git branch -d <feature-branch>
+```
+
+**Option 2 — Create PR:**
+```bash
+git push -u origin <feature-branch>
+gh pr create --title "<title>" --body "## Summary
+- <bullet of what changed>
+
+## Test Plan
+- [ ] <verification steps>"
+```
+
+**Option 3 — Keep as-is:**
+Report: "Branch `<name>` kept. No changes made."
+
+**Option 4 — Discard:**
+Require typed confirmation first:
+```
+This will permanently delete branch <name> and all its commits.
+Type 'discard' to confirm.
+```
+Then:
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+## Red Flags — Never
+- Proceed with failing tests
+- Merge without re-running tests on merged result
+- Delete work without typed confirmation
+- Force-push without explicit user request
+- Add extra options beyond the 4 listed