@xynogen/pix-skills 0.1.0

package/skills/handoff.md

@@ -0,0 +1,121 @@
+---
+name: handoff
+description: Toggle session handoff — if HANDOFF.md does not exist, write one (giving mode); if it exists, read and delete it (receiving mode)
+disable-model-invocation: true
+---
+
+# Handoff Directive
+
+## Overview
+
+Single-agent session handoff via toggle. One session closes, next picks up exactly where it left off.
+
+**Core principle:** Detect file → Give or Receive → Leave no loose ends.
+
+## Below are what agent MUST do:
+
+### Step 1: Detect Mode
+
+```bash
+test -f HANDOFF.md && echo "RECEIVING" || echo "GIVING"
+```
+
+- Output `GIVING` → proceed to **Giving Mode**
+- Output `RECEIVING` → proceed to **Receiving Mode**
+
+---
+
+### Giving Mode
+
+> No `HANDOFF.md` found. This session closing.
+
+**Step 1: Gather context from current conversation + codebase**
+
+Collect all of the following — summarize if long, but never drop critical decisions or failures:
+
+- What is being built and why (goal)
+- Where progress stands right now (current state)
+- Which files actively being modified (files in flight)
+- What changed this session (touched files + what changed)
+- Every failed attempt with its reason — **most critical section**
+- Single next concrete action for next session
+
+**Step 2: Write `HANDOFF.md` in repo root using this exact structure**
+
+```markdown
+# Handoff — [feature / work area name]
+**Date:** YYYY-MM-DD
+
+## Goal
+[What is being built and why — one short paragraph]
+
+## Current State
+[What works, what doesn't, where things stand]
+
+## Files in Flight
+- `path/to/file.ext` — [why this file is relevant]
+
+## Changed
+- `path/to/file.ext` — [what changed this session]
+
+## Failed Attempts
+- ❌ [What was tried] — [why it failed / what error appeared]
+
+## Next Step
+[The one concrete thing to do first in the next session]
+```
+
+**Step 3: Confirm to user**
+
+```
+Handoff written → HANDOFF.md
+Next session: call this skill again to resume.
+```
+
+---
+
+### Receiving Mode
+
+> `HANDOFF.md` found. Previous session left context.
+
+**Step 1: Read the file**
+
+```bash
+cat HANDOFF.md
+```
+
+**Step 2: Internalize before doing anything**
+
+- Understand goal and current state fully
+- Register all **Failed Attempts** — do not retry anything listed here
+- Note **Files in Flight** as starting point for code exploration
+- Treat **Next Step** as first action to execute
+
+**Step 3: Delete the file**
+
+```bash
+rm HANDOFF.md
+```
+
+Deleted immediately so next session starts fresh in giving mode.
+
+**Step 4: Confirm and continue**
+
+```
+Handoff received. Resuming from:
+→ [Next Step content]
+
+Skipping: [brief list of Failed Attempts to avoid]
+```
+
+Then execute Next Step directly — don't ask user to repeat context already in the handoff.
+
+---
+
+## Red Flags — Never
+
+- Skip mode detection step
+- Write handoff without **Failed Attempts** section — even if empty, write `(none this session)`
+- Leave `HANDOFF.md` on disk after receiving it
+- Ask user to re-explain context already captured in handoff file
+- Retry anything explicitly listed under Failed Attempts

package/skills/plan.md

@@ -0,0 +1,62 @@
+---
+name: plan
+description: Write detailed, bite-sized implementation plans before touching code
+disable-model-invocation: true
+---
+# Plan Directive
+
+## Overview
+Write comprehensive implementation plan assuming engineer has zero context for codebase and questionable taste. Document everything they need: which files to touch, exact code, exact commands, how to verify each step. DRY. YAGNI. TDD. Frequent commits.
+
+## Below are what agent MUST do:
+
+### Plan Document Header
+Every plan MUST start with this header:
+```markdown
+# [Feature Name] Implementation Plan
+
+**Goal:** [One sentence describing what this builds]
+**Architecture:** [2-3 sentences about approach]
+**Tech Stack:** [Key technologies/libraries]
+---
+```
+
+### Task Structure
+Each task MUST follow this format:
+```markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+[exact test code]
+
+**Step 2: Run test to verify it fails**
+Run: `[exact command]`
+Expected: FAIL with "[expected error message]"
+
+**Step 3: Write minimal implementation**
+[exact implementation code]
+
+**Step 4: Run test to verify it passes**
+Run: `[exact command]`
+Expected: PASS
+
+**Step 5: Commit**
+`git commit -m "feat: [description]"`
+```
+
+### Rules
+- **Exact file paths always** — no vague "add to the service file"
+- **Complete code in plan** — not "add validation here"
+- **Exact commands with expected output** — no ambiguity
+- **Bite-sized steps** — each step 2-5 minutes of work
+- **TDD enforced** — every task starts with failing test
+
+### Save and Handoff
+- Save plan to `docs/plans/YYYY-MM-DD-<feature-name>.md`
+- Commit plan document
+- Announce: "Plan complete. Ready to execute via `/task`."

package/skills/readme.md

@@ -0,0 +1,79 @@
+---
+name: readme
+description: Create or update a project README in a fixed, deployment-focused style with required sections, env-var tables, and an enforced tone
+disable-model-invocation: true
+---
+# README Directive
+
+## Core Philosophy
+Produce README aimed at deployment engineer or new developer who needs to run project locally and integrate it into a platform. Optimize for: can they get it running in five minutes, do they know which knobs safe to turn in production? No marketing language, no hobbyist framing.
+
+## Below are what agent MUST do:
+
+### Phase 1: Gather Inputs (Before Writing)
+- **AUTO-RUN**: Run terminal commands and tool calls needed proactively without confirmation unless explicit input required.
+- **DETECT EXISTING**: `README.md` already exists → read it first as source of truth for name, purpose, documented endpoints. Treat update as rewrite into this style, preserving factual content.
+- **SCAN**: Read `.env.example`, route files, `docker-compose.yml`, task runner files (`justfile`, `Makefile`, `mise.toml`, `Taskfile.yml`, `package.json`), main entrypoint to gather source material.
+- **NO GUESSING**: Never invent env var names, endpoints, default values, ports, commands. Required input below unknown after scanning → ask user before writing.
+
+Following inputs MUST be identified before drafting:
+
+| # | Input | Notes |
+|---|---|---|
+| 1 | Service/library name, language, one-line purpose | What it accepts, what it produces |
+| 2 | Key operational characteristics | Latency, concurrency, multi-tenancy — 1-2 sentences max |
+| 3 | Runtime requirements | Language version, native deps, CLI tools |
+| 4 | Entrypoint command + local run | Task runner recipes if present (`just`, `make`, `mise`, `npm`) |
+| 5 | Environment variables | Split into three buckets (see Phase 2) |
+| 6 | Container workflow | Whether `docker-compose.yml` or `Dockerfile` exists |
+| 7 | Authentication scheme | Exact login endpoint, header format, fallbacks (query param, cookie) |
+| 8 | HTTP/API surface | Grouped by feature area; common request envelope or response shape |
+| 9 | Interactive docs URL | Swagger/OpenAPI/Storybook if served |
+| 10 | Development task-runner recipes | `test`, `codegen`, `tidy`, `lint` |
+| 11 | License | Exact license name |
+
+### Phase 2: Environment Variable Buckets
+Split every env var into exactly one of these three buckets. Bucket empty for project → OMIT its table, don't pad with empty rows.
+
+| Bucket | Table Columns | Purpose |
+|---|---|---|
+| Required application secrets | `Variable` (left-aligned `\|:---\|`), `Description` | No defaults — must be set before running |
+| Infra-tunable runtime values | `Variable` (left-aligned `\|:---\|`), `Default` (right-aligned `\|---:\|`), `Description` | Sensible defaults, safe to override per environment |
+| Optional feature toggles / external integrations | `Variable` (left-aligned `\|:---\|`), `Default` (right-aligned `\|---:\|`), `Description` | Feature flags, third-party API keys |
+
+### Phase 3: Required Structure (Sections in Order)
+1. `# <Full Name> (<Acronym>)` — acronym only if one exists.
+2. Opening paragraph (2-3 sentences): what service is, what it ingests, what it emits.
+3. Separate short paragraph: key operational characteristics.
+4. `## Table of Contents` — bulleted list of section headings below.
+5. `## Requirements` — bullet list of runtime prerequisites.
+6. `## Quick Start` — copy `.env.example` → `.env`, set minimum required vars (show secret generation, e.g. `openssl rand -hex 32`), then run command(s). End with default listen address.
+7. `## Environment Configuration` — one orienting sentence, then three env tables in bucket order. Close with one-paragraph note about keeping `.env` out of git and injecting via platform secrets in deployments.
+8. `## Docker Compose` — ONLY if compose file exists. One sentence describing what it does, the `docker compose up --build` command, note that deployment platforms can supply same vars directly.
+9. `## Authentication` — login endpoint as `text` code block, then both auth methods (bearer header preferred, query param fallback) in separate code blocks.
+10. `## API Overview` — JSON response envelope as `json` code block, then single table grouping endpoints by feature area (columns: `Group`, `Endpoints`). Below table, short paragraph naming common query parameters spanning multiple endpoints.
+11. `## Documentation` — one sentence, then interactive docs URL in `text` code block.
+12. `## Development` — `bash` code block listing most-used task-runner recipes (`test`, `codegen`, `tidy`), then one-line note about where annotations or generated artifacts live.
+13. `## License` — one line.
+
+### Phase 4: Style Rules (Enforce Strictly)
+- **PROSE**: Plain factual. No marketing words ("blazing fast", "powerful", "easy", "simple"). No emojis. No badges. No screenshots.
+- **ORIENTING SENTENCE**: Every section starts with one orienting sentence before any code, list, or table.
+- **TABLES OVER BULLETS**: Use tables for structured data (env vars, endpoints). Never use bullet lists for things with columns.
+- **CODE FENCES**: Always carry explicit language tag, but stick to widely-supported ones (`bash`, `text`, `json`, `yaml`, `sql`). Avoid obscure tags like `http`, `dotenv`, `ini` — renderers (GitLab, some Markdown viewers) flag them unsupported, display block in red. Use `text` for raw HTTP request lines / headers or env files, `bash` for `curl` examples.
+- **CONCRETE DEFAULTS**: Show actual values inline (`8080`, `30`, `10485760`). Never write "configurable" without actual default.
+- **ENV FORMAT**: Value belongs in `.env` → show as real assignment, not prose.
+- **ENDPOINTS**: In tables use backticks. HTTP methods uppercase, inside backticks: `` `GET /api/streams` ``.
+- **OMIT**: No "Contributing", "Acknowledgments", "What is X?", or "About" sections unless explicitly requested.
+- **OPENING**: Open with what it does, not what it is for.
+
+### Phase 5: Customization Rules
+- **MISSING BUCKET**: Project has no infra-tunable middle tier or no optional integrations → omit that table rather than padding.
+- **NO COMPOSE**: Omit `## Docker Compose` section entirely if no compose file exists.
+- **NO AUTH**: Service unauthenticated → omit `## Authentication`.
+- **NO INTERACTIVE DOCS**: No Swagger/OpenAPI/Storybook served → omit `## Documentation`.
+- **MULTI-LANGUAGE MONOREPO**: Ask user which component README targets before writing.
+- **EXISTING README**: Present diff of proposed changes, ask confirmation before overwriting non-trivial existing README.
+
+## Report
+After writing, output final file path and one-line summary of which optional sections omitted (and why).

package/skills/review.md

@@ -0,0 +1,50 @@
+---
+name: review
+description: Architectural Review and Quality Assurance
+disable-model-invocation: true
+---
+# Review Directive
+
+## Persona
+You are a **bad-mood reviewer** going by the book faithfully. No charity, no benefit of the doubt. Code under review written by competing AI agent. Assume wrong until proven otherwise. Cite the rule violated. No praise, no softening.
+
+## Below are what agent MUST do:
+
+### Pre-Review Checklist (Before Requesting Review)
+- **SELF-REVIEW**: Read every changed line. Would you be embarrassed to show this?
+- **TESTS**: All tests pass. New behavior has tests. No skipped tests without explanation.
+- **SCOPE**: Changes limited to what was planned. No unrelated modifications.
+- **DOCS**: Public interfaces documented. README updated if behavior changed.
+- **CLEAN**: No debug logs, commented-out code, or TODO left behind.
+
+### Review Phases
+- **PHASES**: Verify logic follows proper ordering and dependencies.
+- **IDEMPOTENCY**: Ensure scripts and commands safely repeatable without side effects.
+- **CONSISTENCY**: Check adherence to project naming, structure, style conventions.
+- **INTEGRITY**: Verify imports, links, cross-module dependencies intact.
+- **SECURITY**: No hardcoded secrets, credentials, or unsafe inputs.
+- **YAGNI**: Feature or endpoint unused → flag for removal, don't "implement it properly."
+
+### Receiving Review Feedback
+- **NO PERFORMATIVE AGREEMENT**: Never say "Great point!", "You're absolutely right!", or "Thanks for catching that!" Just fix it or push back. Actions speak.
+- **UNDERSTAND FIRST**: Before implementing anything, restate requirement in your own words. Any item unclear → stop and ask, don't implement the ones you understand while deferring the unclear ones.
+- **VERIFY BEFORE IMPLEMENTING**: Check if suggestion technically correct for *this* codebase. Does it break existing functionality? Conflict with prior architectural decisions?
+- **YAGNI CHECK**: Reviewer suggests adding feature → grep codebase first. Nothing calls it → push back: "This isn't used anywhere — remove it (YAGNI)?"
+- **PUSH BACK WHEN WRONG**: Use technical reasoning, not defensiveness. Reference working tests or code. Involve user if architectural.
+- **IMPLEMENTATION ORDER**: Fix blocking issues first (crashes, security), then simple fixes (typos), then complex refactors. Test each fix individually.
+
+### Acknowledging Correct Feedback
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch — [specific issue]. Fixed in [location]."
+✅ [Just fix it and show the diff]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+```
+
+### Verdict
+- **VERDICT**: Provide clear **Pass / Pass with Suggestions / Fail** report with technical rationale.
+- **FAIL** means: critical logic errors, missing tests, security issues, or broken contracts.
+- **Pass with Suggestions** means: works correctly but has improvement opportunities.