@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/skills/plan-writing/SKILL.md

@@ -1,152 +1,152 @@
----
-name: plan-writing
-description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
-allowed-tools: Read, Glob, Grep
----
-
-# Plan Writing
-
-> Source: obra/superpowers
-
-## Overview
-This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
-
-## Task Breakdown Principles
-
-### 1. Small, Focused Tasks
-- Each task should take 2-5 minutes
-- One clear outcome per task
-- Independently verifiable
-
-### 2. Clear Verification
-- How do you know it's done?
-- What can you check/test?
-- What's the expected output?
-
-### 3. Logical Ordering
-- Dependencies identified
-- Parallel work where possible
-- Critical path highlighted
-- **Phase X: Verification is always LAST**
-
-### 4. Dynamic Naming in Project Root
-- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
-- Name derived from task (e.g., "add auth" → `auth-feature.md`)
-- **NEVER** inside `.claude/`, `docs/`, or temp folders
-
-## Planning Principles (NOT Templates!)
-
-> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
-
-### Principle 1: Keep It SHORT
-
-| ❌ Wrong | ✅ Right |
-|----------|----------|
-| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
-| Every micro-step listed | Only actionable items |
-| Verbose descriptions | One-line per task |
-
-> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
-
----
-
-### Principle 2: Be SPECIFIC, Not Generic
-
-| ❌ Wrong | ✅ Right |
-|----------|----------|
-| "Set up project" | "Run `npx create-next-app`" |
-| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
-| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
-
-> **Rule:** Each task should have a clear, verifiable outcome.
-
----
-
-### Principle 3: Dynamic Content Based on Project Type
-
-**For NEW PROJECT:**
-- What tech stack? (decide first)
-- What's the MVP? (minimal features)
-- What's the file structure?
-
-**For FEATURE ADDITION:**
-- Which files are affected?
-- What dependencies needed?
-- How to verify it works?
-
-**For BUG FIX:**
-- What's the root cause?
-- What file/line to change?
-- How to test the fix?
-
----
-
-### Principle 4: Scripts Are Project-Specific
-
-> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
-
-| Project Type | Relevant Scripts |
-|--------------|------------------|
-| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
-| Backend/API | `api_validator.py`, `security_scan.py` |
-| Mobile | `mobile_audit.py` |
-| Database | `schema_validator.py` |
-| Full-stack | Mix of above based on what you touched |
-
-**Wrong:** Adding all scripts to every plan
-**Right:** Only scripts relevant to THIS task
-
----
-
-### Principle 5: Verification is Simple
-
-| ❌ Wrong | ✅ Right |
-|----------|----------|
-| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
-| "Test the API" | "curl localhost:3000/api/users returns 200" |
-| "Check styles" | "Open browser, verify dark mode toggle works" |
-
----
-
-## Plan Structure (Flexible, Not Fixed!)
-
-```
-# [Task Name]
-
-## Goal
-One sentence: What are we building/fixing?
-
-## Tasks
-- [ ] Task 1: [Specific action] → Verify: [How to check]
-- [ ] Task 2: [Specific action] → Verify: [How to check]
-- [ ] Task 3: [Specific action] → Verify: [How to check]
-
-## Done When
-- [ ] [Main success criteria]
-```
-
-> **That's it.** No phases, no sub-sections unless truly needed.
-> Keep it minimal. Add complexity only when required.
-
-## Notes
-[Any important considerations]
-```
-
----
-
-## Best Practices (Quick Reference)
-
-1. **Start with goal** - What are we building/fixing?
-2. **Max 10 tasks** - If more, break into multiple plans
-3. **Each task verifiable** - Clear "done" criteria
-4. **Project-specific** - No copy-paste templates
-5. **Update as you go** - Mark `[x]` when complete
-
----
-
-## When to Use
-
-- New project from scratch
-- Adding a feature
-- Fixing a bug (if complex)
-- Refactoring multiple files
+---
+name: plan-writing
+description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
+allowed-tools: Read, Glob, Grep
+---
+
+# Plan Writing
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
+
+## Task Breakdown Principles
+
+### 1. Small, Focused Tasks
+- Each task should take 2-5 minutes
+- One clear outcome per task
+- Independently verifiable
+
+### 2. Clear Verification
+- How do you know it's done?
+- What can you check/test?
+- What's the expected output?
+
+### 3. Logical Ordering
+- Dependencies identified
+- Parallel work where possible
+- Critical path highlighted
+- **Phase X: Verification is always LAST**
+
+### 4. Dynamic Naming in Project Root
+- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
+- Name derived from task (e.g., "add auth" → `auth-feature.md`)
+- **NEVER** inside `.claude/`, `docs/`, or temp folders
+
+## Planning Principles (NOT Templates!)
+
+> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
+
+### Principle 1: Keep It SHORT
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
+| Every micro-step listed | Only actionable items |
+| Verbose descriptions | One-line per task |
+
+> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
+
+---
+
+### Principle 2: Be SPECIFIC, Not Generic
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Set up project" | "Run `npx create-next-app`" |
+| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
+| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
+
+> **Rule:** Each task should have a clear, verifiable outcome.
+
+---
+
+### Principle 3: Dynamic Content Based on Project Type
+
+**For NEW PROJECT:**
+- What tech stack? (decide first)
+- What's the MVP? (minimal features)
+- What's the file structure?
+
+**For FEATURE ADDITION:**
+- Which files are affected?
+- What dependencies needed?
+- How to verify it works?
+
+**For BUG FIX:**
+- What's the root cause?
+- What file/line to change?
+- How to test the fix?
+
+---
+
+### Principle 4: Scripts Are Project-Specific
+
+> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
+
+| Project Type | Relevant Scripts |
+|--------------|------------------|
+| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
+| Backend/API | `api_validator.py`, `security_scan.py` |
+| Mobile | `mobile_audit.py` |
+| Database | `schema_validator.py` |
+| Full-stack | Mix of above based on what you touched |
+
+**Wrong:** Adding all scripts to every plan
+**Right:** Only scripts relevant to THIS task
+
+---
+
+### Principle 5: Verification is Simple
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
+| "Test the API" | "curl localhost:3000/api/users returns 200" |
+| "Check styles" | "Open browser, verify dark mode toggle works" |
+
+---
+
+## Plan Structure (Flexible, Not Fixed!)
+
+```
+# [Task Name]
+
+## Goal
+One sentence: What are we building/fixing?
+
+## Tasks
+- [ ] Task 1: [Specific action] → Verify: [How to check]
+- [ ] Task 2: [Specific action] → Verify: [How to check]
+- [ ] Task 3: [Specific action] → Verify: [How to check]
+
+## Done When
+- [ ] [Main success criteria]
+```
+
+> **That's it.** No phases, no sub-sections unless truly needed.
+> Keep it minimal. Add complexity only when required.
+
+## Notes
+[Any important considerations]
+```
+
+---
+
+## Best Practices (Quick Reference)
+
+1. **Start with goal** - What are we building/fixing?
+2. **Max 10 tasks** - If more, break into multiple plans
+3. **Each task verifiable** - Clear "done" criteria
+4. **Project-specific** - No copy-paste templates
+5. **Update as you go** - Mark `[x]` when complete
+
+---
+
+## When to Use
+
+- New project from scratch
+- Adding a feature
+- Fixing a bug (if complex)
+- Refactoring multiple files

package/.agent/skills/plankton-code-quality/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: plankton-code-quality
+description: "Write-time code quality enforcement using Plankton — auto-formatting, linting, and Claude-powered fixes on every file edit via hooks."
+origin: community
+---
+
+# Plankton Code Quality Skill
+
+Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch.
+
+## When to Use
+
+- You want automatic formatting and linting on every file edit (not just at commit time)
+- You need defense against agents modifying linter configs to pass instead of fixing code
+- You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types)
+- You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)
+
+## How It Works
+
+### Three-Phase Architecture
+
+Every time Claude Code edits or writes a file, Plankton's `multi_linter.sh` PostToolUse hook runs:
+
+```
+Phase 1: Auto-Format (Silent)
+├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
+├─ Fixes 40-50% of issues silently
+└─ No output to main agent
+
+Phase 2: Collect Violations (JSON)
+├─ Runs linters and collects unfixable violations
+├─ Returns structured JSON: {line, column, code, message, linter}
+└─ Still no output to main agent
+
+Phase 3: Delegate + Verify
+├─ Spawns claude -p subprocess with violations JSON
+├─ Routes to model tier based on violation complexity:
+│   ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
+│   ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout
+│   └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
+├─ Re-runs Phase 1+2 to verify fixes
+└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)
+```
+
+### What the Main Agent Sees
+
+| Scenario | Agent sees | Hook exit |
+|----------|-----------|-----------|
+| No violations | Nothing | 0 |
+| All fixed by subprocess | Nothing | 0 |
+| Violations remain after subprocess | `[hook] N violation(s) remain` | 2 |
+| Advisory (duplicates, old tooling) | `[hook:advisory] ...` | 0 |
+
+The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently.
+
+### Config Protection (Defense Against Rule-Gaming)
+
+LLMs will modify `.ruff.toml` or `biome.json` to disable rules rather than fix code. Plankton blocks this with three layers:
+
+1. **PreToolUse hook** — `protect_linter_configs.sh` blocks edits to all linter configs before they happen
+2. **Stop hook** — `stop_config_guardian.sh` detects config changes via `git diff` at session end
+3. **Protected files list** — `.ruff.toml`, `biome.json`, `.shellcheckrc`, `.yamllint`, `.hadolint.yaml`, and more
+
+### Package Manager Enforcement
+
+A PreToolUse hook on Bash blocks legacy package managers:
+- `pip`, `pip3`, `poetry`, `pipenv` → Blocked (use `uv`)
+- `npm`, `yarn`, `pnpm` → Blocked (use `bun`)
+- Allowed exceptions: `npm audit`, `npm view`, `npm publish`
+
+## Setup
+
+### Quick Start
+
+> **Note:** Plankton requires manual installation from its repository. Review the code before installing.
+
+```bash
+# Install core dependencies
+brew install jaq ruff uv
+
+# Install Python linters
+uv sync --all-extras
+
+# Start Claude Code — hooks activate automatically
+claude
+```
+
+No install command, no plugin config. The hooks in `.claude/settings.json` are picked up automatically when you run Claude Code in the Plankton directory.
+
+### Per-Project Integration
+
+To use Plankton hooks in your own project:
+
+1. Copy `.claude/hooks/` directory to your project
+2. Copy `.claude/settings.json` hook configuration
+3. Copy linter config files (`.ruff.toml`, `biome.json`, etc.)
+4. Install the linters for your languages
+
+### Language-Specific Dependencies
+
+| Language | Required | Optional |
+|----------|----------|----------|
+| Python | `ruff`, `uv` | `ty` (types), `vulture` (dead code), `bandit` (security) |
+| TypeScript/JS | `biome` | `oxlint`, `semgrep`, `knip` (dead exports) |
+| Shell | `shellcheck`, `shfmt` | — |
+| YAML | `yamllint` | — |
+| Markdown | `markdownlint-cli2` | — |
+| Dockerfile | `hadolint` (>= 2.12.0) | — |
+| TOML | `taplo` | — |
+| JSON | `jaq` | — |
+
+## Pairing with ECC
+
+### Complementary, Not Overlapping
+
+| Concern | ECC | Plankton |
+|---------|-----|----------|
+| Code quality enforcement | PostToolUse hooks (Prettier, tsc) | PostToolUse hooks (20+ linters + subprocess fixes) |
+| Security scanning | AgentShield, security-reviewer agent | Bandit (Python), Semgrep (TypeScript) |
+| Config protection | — | PreToolUse blocks + Stop hook detection |
+| Package manager | Detection + setup | Enforcement (blocks legacy PMs) |
+| CI integration | — | Pre-commit hooks for git |
+| Model routing | Manual (`/model opus`) | Automatic (violation complexity → tier) |
+
+### Recommended Combination
+
+1. Install ECC as your plugin (agents, skills, commands, rules)
+2. Add Plankton hooks for write-time quality enforcement
+3. Use AgentShield for security audits
+4. Use ECC's verification-loop as a final gate before PRs
+
+### Avoiding Hook Conflicts
+
+If running both ECC and Plankton hooks:
+- ECC's Prettier hook and Plankton's biome formatter may conflict on JS/TS files
+- Resolution: disable ECC's Prettier PostToolUse hook when using Plankton (Plankton's biome is more comprehensive)
+- Both can coexist on different file types (ECC handles what Plankton doesn't cover)
+
+## Configuration Reference
+
+Plankton's `.claude/hooks/config.json` controls all behavior:
+
+```json
+{
+  "languages": {
+    "python": true,
+    "shell": true,
+    "yaml": true,
+    "json": true,
+    "toml": true,
+    "dockerfile": true,
+    "markdown": true,
+    "typescript": {
+      "enabled": true,
+      "js_runtime": "auto",
+      "biome_nursery": "warn",
+      "semgrep": true
+    }
+  },
+  "phases": {
+    "auto_format": true,
+    "subprocess_delegation": true
+  },
+  "subprocess": {
+    "tiers": {
+      "haiku":  { "timeout": 120, "max_turns": 10 },
+      "sonnet": { "timeout": 300, "max_turns": 10 },
+      "opus":   { "timeout": 600, "max_turns": 15 }
+    },
+    "volume_threshold": 5
+  }
+}
+```
+
+**Key settings:**
+- Disable languages you don't use to speed up hooks
+- `volume_threshold` — violations > this count auto-escalate to a higher model tier
+- `subprocess_delegation: false` — skip Phase 3 entirely (just report violations)
+
+## Environment Overrides
+
+| Variable | Purpose |
+|----------|---------|
+| `HOOK_SKIP_SUBPROCESS=1` | Skip Phase 3, report violations directly |
+| `HOOK_SUBPROCESS_TIMEOUT=N` | Override tier timeout |
+| `HOOK_DEBUG_MODEL=1` | Log model selection decisions |
+| `HOOK_SKIP_PM=1` | Bypass package manager enforcement |
+
+## References
+
+- Plankton (credit: @alxfazio)
+- Plankton REFERENCE.md — Full architecture documentation (credit: @alxfazio)
+- Plankton SETUP.md — Detailed installation guide (credit: @alxfazio)
+
+## ECC v1.8 Additions
+
+### Copyable Hook Profile
+
+Set strict quality behavior:
+
+```bash
+export ECC_HOOK_PROFILE=strict
+export ECC_QUALITY_GATE_FIX=true
+export ECC_QUALITY_GATE_STRICT=true
+```
+
+### Language Gate Table
+
+- TypeScript/JavaScript: Biome preferred, Prettier fallback
+- Python: Ruff format/check
+- Go: gofmt
+
+### Config Tamper Guard
+
+During quality enforcement, flag changes to config files in same iteration:
+
+- `biome.json`, `.eslintrc*`, `prettier.config*`, `tsconfig.json`, `pyproject.toml`
+
+If config is changed to suppress violations, require explicit review before merge.
+
+### CI Integration Pattern
+
+Use the same commands in CI as local hooks:
+
+1. run formatter checks
+2. run lint/type checks
+3. fail fast on strict mode
+4. publish remediation summary
+
+### Health Metrics
+
+Track:
+- edits flagged by gates
+- average remediation time
+- repeat violations by category
+- merge blocks due to gate failures

package/.agent/skills/postgres-patterns/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: postgres-patterns
+description: PostgreSQL database patterns for query optimization, schema design, indexing, and security. Based on Supabase best practices.
+origin: ECC
+---
+
+# PostgreSQL Patterns
+
+Quick reference for PostgreSQL best practices. For detailed guidance, use the `database-reviewer` agent.
+
+## When to Activate
+
+- Writing SQL queries or migrations
+- Designing database schemas
+- Troubleshooting slow queries
+- Implementing Row Level Security
+- Setting up connection pooling
+
+## Quick Reference
+
+### Index Cheat Sheet
+
+| Query Pattern | Index Type | Example |
+|--------------|------------|---------|
+| `WHERE col = value` | B-tree (default) | `CREATE INDEX idx ON t (col)` |
+| `WHERE col > value` | B-tree | `CREATE INDEX idx ON t (col)` |
+| `WHERE a = x AND b > y` | Composite | `CREATE INDEX idx ON t (a, b)` |
+| `WHERE jsonb @> '{}'` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| `WHERE tsv @@ query` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| Time-series ranges | BRIN | `CREATE INDEX idx ON t USING brin (col)` |
+
+### Data Type Quick Reference
+
+| Use Case | Correct Type | Avoid |
+|----------|-------------|-------|
+| IDs | `bigint` | `int`, random UUID |
+| Strings | `text` | `varchar(255)` |
+| Timestamps | `timestamptz` | `timestamp` |
+| Money | `numeric(10,2)` | `float` |
+| Flags | `boolean` | `varchar`, `int` |
+
+### Common Patterns
+
+**Composite Index Order:**
+```sql
+-- Equality columns first, then range columns
+CREATE INDEX idx ON orders (status, created_at);
+-- Works for: WHERE status = 'pending' AND created_at > '2024-01-01'
+```
+
+**Covering Index:**
+```sql
+CREATE INDEX idx ON users (email) INCLUDE (name, created_at);
+-- Avoids table lookup for SELECT email, name, created_at
+```
+
+**Partial Index:**
+```sql
+CREATE INDEX idx ON users (email) WHERE deleted_at IS NULL;
+-- Smaller index, only includes active users
+```
+
+**RLS Policy (Optimized):**
+```sql
+CREATE POLICY policy ON orders
+  USING ((SELECT auth.uid()) = user_id);  -- Wrap in SELECT!
+```
+
+**UPSERT:**
+```sql
+INSERT INTO settings (user_id, key, value)
+VALUES (123, 'theme', 'dark')
+ON CONFLICT (user_id, key)
+DO UPDATE SET value = EXCLUDED.value;
+```
+
+**Cursor Pagination:**
+```sql
+SELECT * FROM products WHERE id > $last_id ORDER BY id LIMIT 20;
+-- O(1) vs OFFSET which is O(n)
+```
+
+**Queue Processing:**
+```sql
+UPDATE jobs SET status = 'processing'
+WHERE id = (
+  SELECT id FROM jobs WHERE status = 'pending'
+  ORDER BY created_at LIMIT 1
+  FOR UPDATE SKIP LOCKED
+) RETURNING *;
+```
+
+### Anti-Pattern Detection
+
+```sql
+-- Find unindexed foreign keys
+SELECT conrelid::regclass, a.attname
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_index i
+    WHERE i.indrelid = c.conrelid AND a.attnum = ANY(i.indkey)
+  );
+
+-- Find slow queries
+SELECT query, mean_exec_time, calls
+FROM pg_stat_statements
+WHERE mean_exec_time > 100
+ORDER BY mean_exec_time DESC;
+
+-- Check table bloat
+SELECT relname, n_dead_tup, last_vacuum
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 1000
+ORDER BY n_dead_tup DESC;
+```
+
+### Configuration Template
+
+```sql
+-- Connection limits (adjust for RAM)
+ALTER SYSTEM SET max_connections = 100;
+ALTER SYSTEM SET work_mem = '8MB';
+
+-- Timeouts
+ALTER SYSTEM SET idle_in_transaction_session_timeout = '30s';
+ALTER SYSTEM SET statement_timeout = '30s';
+
+-- Monitoring
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- Security defaults
+REVOKE ALL ON SCHEMA public FROM public;
+
+SELECT pg_reload_conf();
+```
+
+## Related
+
+- Agent: `database-reviewer` - Full database review workflow
+- Skill: `clickhouse-io` - ClickHouse analytics patterns
+- Skill: `backend-patterns` - API and backend patterns
+
+---
+
+*Based on Supabase Agent Skills (credit: Supabase team) (MIT License)*