panopticon-cli 0.4.32 → 0.4.33

package/skills/pan-tldr/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: pan-tldr
+description: TLDR code analysis — token-efficient codebase understanding. Use before reading large files.
+triggers:
+  - tldr
+  - code analysis
+  - understand codebase
+  - explore code
+  - what does this file do
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# TLDR Code Analysis
+
+## What It Is
+
+TLDR is a 5-layer code analysis tool that produces structured summaries using 500-1,200 tokens per file instead of 10-25k for raw reads. It extends how much work you can accomplish per session by 10-20x.
+
+## When to Use TLDR
+
+**Always use TLDR first when:**
+- Exploring unfamiliar code (use `tldr context` or `tldr structure`)
+- Understanding function relationships (use `tldr calls` or `tldr impact`)
+- Searching code by description (use `tldr semantic`)
+- Planning changes across multiple files
+
+**Read the full file when:**
+- You need exact line numbers for editing
+- The file is small (< 3KB)
+- You need config files, docs, or non-code files
+- TLDR context wasn't sufficient for the specific section
+
+## Decision Tree
+
+```
+Need to understand a file?
+├── Small file (< 3KB) → Read directly
+├── Need exact content for editing → Read with offset/limit
+└── Understanding structure/relationships → Use TLDR first
+    ├── "What does this file export?" → tldr context <file>
+    ├── "What's in this directory?" → tldr structure <dir>
+    ├── "What calls this function?" → tldr calls <func> <file>
+    ├── "What does this function call?" → tldr impact <func> <file>
+    ├── "Find code that handles X" → tldr semantic "X"
+    └── "Show me the architecture" → tldr arch <dir>
+```
+
+## Available Commands
+
+All commands run from the workspace root. The binary is at `.venv/bin/tldr`.
+
+### Exploration
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `tldr context <file>` | File structure, exports, imports, key functions | ~800 |
+| `tldr structure <dir>` | Directory layout and relationships | ~500 |
+| `tldr tree <dir>` | File tree with language detection | ~200 |
+| `tldr arch <dir>` | Architectural overview | ~600 |
+
+### Relationships
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `tldr calls <file>` | What calls functions in this file (callers) | ~400 |
+| `tldr impact <func> <file>` | What this function calls (callees) | ~400 |
+| `tldr imports <file>` | What this file imports | ~200 |
+| `tldr importers <file>` | What files import this one | ~200 |
+
+### Analysis
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `tldr cfg <func> <file>` | Control flow graph | ~300 |
+| `tldr dfg <func> <file>` | Data flow graph | ~300 |
+| `tldr slice <func> <file>` | Program slice (dependency chain) | ~400 |
+| `tldr dead <dir>` | Dead code detection | ~500 |
+| `tldr change-impact <file>` | Files affected by changes to this file | ~300 |
+| `tldr diagnostics <file>` | Type errors and lint issues | ~200 |
+
+### Search
+
+| Command | Purpose | Tokens |
+|---------|---------|--------|
+| `tldr search <pattern> <dir>` | Structural code search (AST-aware) | ~400 |
+| `tldr semantic "query"` | Natural language code search (embedding-based) | ~500 |
+| `tldr extract <symbol> <file>` | Extract specific function/class definition | ~300 |
+
+## MCP Tools (if configured)
+
+When TLDR is set up as an MCP server, Claude Code agents get these tools natively:
+- `tldr_context <file>` — File structure overview
+- `tldr_structure <directory>` — Directory layout
+- `tldr_calls <function> <file>` — Call graph (callers)
+- `tldr_impact <function> <file>` — Impact analysis (callees)
+- `tldr_semantic <query>` — Natural language search
+
+## Hook Integration
+
+TLDR hooks run automatically:
+
+- **Read enforcer** (PreToolUse): Intercepts reads on large code files (> 3KB) and returns TLDR summaries instead. To read the full file, use `Read` with `offset` and `limit` parameters.
+- **Post-edit notify** (PostToolUse): Tracks edited files and triggers background re-warm after 10 edits to keep the index fresh.
+
+## Index Management
+
+```bash
+# Check index status
+pan tldr status
+
+# Manually warm/rebuild the index
+pan tldr warm
+
+# Start/stop the daemon
+pan tldr start
+pan tldr stop
+```
+
+The index is built automatically:
+- On workspace creation (background warm after daemon start)
+- After merges to main (merge-agent triggers re-warm)
+- After 10 code file edits (post-edit hook triggers re-warm)
+- On `pan up` (main daemon starts)
+
+## Token Savings Example
+
+```
+Without TLDR:
+  20 files x 15,000 tokens = 300,000 tokens (exhausts context)
+
+With TLDR:
+  20 files x 800 tokens = 16,000 tokens (94% savings)
+  + 3 full reads for editing = 45,000 tokens
+  Total: 61,000 tokens — can do 5x more work per session
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `tldr: command not found` | Run from workspace root: `.venv/bin/tldr` |
+| No `.venv` directory | `python3 -m venv .venv && .venv/bin/pip install llm-tldr` |
+| Stale index | `pan tldr warm` or `.venv/bin/tldr warm .` |
+| Empty results | Check `.tldrignore` isn't excluding your files |
+| Daemon not running | `pan tldr start` or it auto-starts with `pan up` |

package/skills/react-best-practices/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-transitions` - Use startTransition for non-urgent updates
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+rules/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

package/skills/spec-readiness/REPORT-TEMPLATE.md

@@ -0,0 +1,158 @@
+# Spec Readiness — Report Template
+
+This file defines the report structure for both HTML and EML formats. Only the report-generation subagent reads this.
+
+## Branding
+
+Configurable via wrapper `config.yaml`. Defaults:
+- Primary Color: #1e293b (dark slate — headers, text)
+- Stripe Color: matches primary (top accent bar)
+- Score colors: Red (#E53935) < 8, Yellow (#FF9800) 8-14, Green (#43A047) 15+
+- Status colors: Red = 0-39, Yellow = 40-69, Green = 70-100
+
+If a wrapper `config.yaml` exists, use `branding.primary_color`, `branding.stripe_color`, `branding.company_name`, and `branding.footer_text` from it.
+
+## Report Sections
+
+### 1. Brand Stripe (4px)
+Top-of-page accent bar using `branding.stripe_color` or default.
+
+### 2. Header Block (primary_color background)
+- Eyebrow text: "REQUIREMENTS READINESS ASSESSMENT" (uppercase, small, lighter accent)
+- Title: "{Issue Title}" (white, large)
+- Metadata line: "{Identifier} · {Project} · {Milestone/Release} · Assessed {date}" (light gray)
+- Score badge: Large score number with status label and color (circular or pill badge)
+
+### 3. Issue Info Row (Light Gray background, #F5F5F5)
+Grid/flex row showing:
+- Owner/Assignee
+- Project
+- Milestone/Release dates
+- Child issue count (completed/total)
+- Estimate if set
+
+### 4. Score Dashboard — 5 metric cards in a row/grid
+Each card contains:
+- Dimension name (uppercase label, small text)
+- Score as "X / 20" (large number)
+- Visual bar (colored by score: red < 8, yellow 8-14, green 15+)
+- One-line summary from dimension findings
+
+### 5. Overall Score Bar
+- Full-width progress bar showing 0-100
+- Fill color matches status (red/yellow/green)
+- Status label badge aligned right
+- Score number displayed inside or above bar
+
+### 6. Top Blockers (Amber/warning callout box)
+- Background: light amber (#FFF8E1)
+- Border-left: 4px solid #FF9800
+- Header: "Top Blockers" with warning icon
+- 3-5 actionable bullets
+- Each with estimated point-improvement in parentheses
+
+### 7. Dimension Details — One section per dimension
+Each section contains:
+- Section heading with dimension name and score badge (colored pill)
+- Findings table with columns: Finding | Impact | Source | Recommendation
+- Row colors: Green background tint for bonus findings, Red tint for deductions, Gray for neutral
+- Impact column shows "+N" or "-N" with color
+
+### 8. External Document Analysis (only if PRD/BRD found)
+- Document source and access status
+- Coverage summary
+- Gaps identified
+- Note if document was attached before or after development started
+
+### 9. Child Issue Assessment Table
+- Columns: ID (linked if possible), Title, Status, Has AC?, AC Quality, Notes
+- AC Quality badges: Good (green pill), Weak (yellow pill), None (red pill)
+- Summary row at bottom: "X of Y issues have testable acceptance criteria"
+- Sortable appearance (styled headers)
+
+### 10. Footer
+- Light gray background
+- Text: `branding.footer_text` or default: "Spec Readiness Assessment · Generated from {tracker} data · {Project}"
+- Sub-text: "Methodology: 5-dimension scoring model"
+- Assessment date
+
+## HTML Format Guidelines
+
+Use when generating `.html` output (default):
+
+- Self-contained single HTML file (inline CSS, no external dependencies)
+- Use `<style>` block in `<head>` for main styles
+- Print-friendly: `@media print` rules for clean printing
+- Table cells: `padding: 8px 12px; border-bottom: 1px solid #E0E0E0`
+- Font stack: `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`
+- Max width: 1000px, centered with `margin: 0 auto`
+- Score badge CSS: `display: inline-block; padding: 4px 12px; border-radius: 12px; font-weight: 600`
+- `open` command opens in browser
+
+## EML Format Guidelines
+
+Use when generating `.eml` output (`--eml` flag):
+
+### MIME Headers
+
+The file must start with RFC 2822 headers, then a blank line, then the HTML body:
+
+```
+MIME-Version: 1.0
+Content-Type: text/html; charset="UTF-8"
+Subject: Spec Readiness: {Identifier} — {Title} ({Score}/100 {StatusLabel})
+From: noreply@example.com
+To: noreply@example.com
+Date: {RFC 2822 date, e.g. Thu, 27 Feb 2026 12:00:00 -0600}
+
+<!DOCTYPE html>
+<html>...
+```
+
+The `From` and `To` addresses are placeholders — the wrapper `config.yaml` can override them via `branding.eml_from` and `branding.eml_to`. Without a wrapper, use `noreply@example.com` as defaults. The user opens the `.eml` in their mail client and edits recipients before sending.
+
+### Email-Safe HTML Constraints
+
+- **All inline CSS** — no `<style>` blocks (many email clients strip them)
+- **Table-based layout** using `<table role="presentation">` — no flexbox/grid
+- **Max width: 560px** — email-friendly width
+- **No external resources** — no linked stylesheets, fonts, or images
+- Font stack: `Arial, 'Helvetica Neue', Helvetica, sans-serif`
+- Use `&nbsp;` in empty cells, `&middot;` for separators
+- `border-collapse: separate` on data tables for border-radius support
+
+### Status Badge Inline Styles
+
+```
+Completed:   background-color:#E6F7F5; color:#00897B; padding:2px 8px; border-radius:10px; font-size:11px;
+In-Progress: background-color:#DBEAFE; color:#1e40af; padding:2px 8px; border-radius:10px; font-size:11px;
+Backlog:     background-color:#F5F5F5; color:#374151; border:1px solid #CFD1D1; padding:2px 8px; border-radius:10px; font-size:11px;
+Blocked:     background-color:#FEE2E2; color:#DC2626; padding:2px 8px; border-radius:10px; font-size:11px;
+```
+
+### Score Badge Inline Styles
+
+```
+Red (0-39):    background-color:#FDECEA; color:#DC2626; padding:4px 12px; border-radius:12px; font-weight:600;
+Yellow (40-69): background-color:#FFF8E1; color:#C2410C; padding:4px 12px; border-radius:12px; font-weight:600;
+Green (70-100): background-color:#E6F7F5; color:#00897B; padding:4px 12px; border-radius:12px; font-weight:600;
+```
+
+### EML Branding Colors (defaults, overridable via wrapper)
+
+- Primary Dark: `branding.primary_color` or `#1e293b` (headers, primary text)
+- Body Text: `#374151` (labels, secondary text)
+- Accent: `branding.stripe_color` or `#2563eb` (brand stripe, accents)
+- Alert Red: `#DC2626`, Amber: `#D97706`, Green: `#00897B`
+
+### Opening
+
+`open` command opens `.eml` in the default mail client (Thunderbird, Mail.app, Outlook).
+
+## JSON Sidecar
+
+Always generated regardless of report format. Schema is defined in SCORING-REFERENCE.md.
+Files save to the same output directory with naming convention:
+- HTML: `spec-readiness-{identifier}.html`
+- EML: `spec-readiness-{identifier}.eml`
+- JSON: `spec-readiness-{identifier}.json`