panopticon-cli 0.4.6 → 0.4.8

package/skills/pan-subagent-creator/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: pan-subagent-creator
+description: Create custom Claude Code subagents with isolated context windows, specific tool permissions, and specialized prompts. Use when users want to create a new subagent, configure agent delegation, set up task-specific agents, or define specialized assistants. Triggers on "create a subagent", "make a custom agent", "define an agent", "agent configuration", or "Task tool agent".
+---
+
+# Subagent Creator
+
+Create specialized subagents that handle specific tasks with their own context windows, system prompts, and tool permissions.
+
+## What Are Subagents?
+
+Subagents are mini-agents with:
+- **Independent context window** - Keep exploration out of main conversation
+- **Custom system prompt** - Specialized behavior and expertise
+- **Scoped tool permissions** - Least-privilege access
+- **Model selection** - Cost optimization (Haiku for read-only, Sonnet for complex)
+
+Claude delegates to subagents via the **Task tool** based on matching descriptions.
+
+## Subagent Anatomy
+
+Subagents are Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: code-reviewer
+description: Expert code review. Use proactively after code changes.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a senior code reviewer focusing on quality, security, and best practices.
+
+[Instructions for the subagent...]
+```
+
+## Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (lowercase, hyphens allowed) |
+| `description` | Yes | When Claude should delegate - this is how Claude decides |
+| `tools` | No | Allowed tools (inherits all if omitted) |
+| `disallowedTools` | No | Tools to explicitly deny |
+| `model` | No | `haiku`, `sonnet`, `opus`, or `inherit` (default: sonnet) |
+| `permissionMode` | No | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
+| `skills` | No | Skills to load at startup |
+| `hooks` | No | Lifecycle hooks for validation |
+
+## Storage Locations
+
+| Location | Scope | Use Case |
+|----------|-------|----------|
+| `.claude/agents/` | Current project | Team-shared subagents |
+| `~/.claude/agents/` | All projects | Personal, reusable subagents |
+| CLI `--agents` flag | Current session | Quick testing |
+
+## Model Selection for Cost
+
+| Model | Cost | Best For |
+|-------|------|----------|
+| **Haiku** | Lowest | Read-only exploration, simple validation |
+| **Sonnet** | Medium | Most tasks, good balance |
+| **Opus** | Highest | Complex reasoning, critical decisions |
+| **inherit** | Parent's | Match main conversation |
+
+## Permission Modes
+
+```yaml
+permissionMode: default        # Normal permission prompts
+permissionMode: acceptEdits    # Auto-accept file edits
+permissionMode: dontAsk        # Auto-deny all prompts
+permissionMode: bypassPermissions  # Skip all checks (dangerous)
+permissionMode: plan           # Read-only exploration mode
+```
+
+## Common Tool Sets
+
+**Read-only agents:**
+```yaml
+tools: Read, Grep, Glob
+```
+
+**Code review agents:**
+```yaml
+tools: Read, Grep, Glob, Bash
+```
+
+**Full development agents:**
+```yaml
+tools: Read, Write, Edit, Bash, Grep, Glob
+```
+
+**Restricted bash (specific commands only):**
+```yaml
+tools: Read, Grep, Glob, Bash(git status:*), Bash(git diff:*)
+```
+
+## Creation Process
+
+### Step 1: Define Purpose
+- What specific task does this agent handle?
+- What expertise should it have?
+- What tools does it need (minimum necessary)?
+
+### Step 2: Write Description
+The description is how Claude decides when to delegate. Make it specific:
+
+**Good:** "Expert database query optimizer. Analyzes SQL queries for performance issues, suggests indexes, and rewrites slow queries."
+
+**Bad:** "Helps with database stuff."
+
+### Step 3: Create Agent File
+
+```bash
+# Project-level (shared with team)
+mkdir -p .claude/agents
+touch .claude/agents/my-agent.md
+
+# User-level (personal)
+mkdir -p ~/.claude/agents
+touch ~/.claude/agents/my-agent.md
+```
+
+### Step 4: Write Instructions
+Use imperative voice. Be specific about:
+- What the agent should do when invoked
+- How to structure output
+- What to avoid
+- Error handling
+
+### Step 5: Test Delegation
+Try prompts that should and shouldn't trigger the agent. Refine description if needed.
+
+## Example: Code Reviewer
+
+```markdown
+---
+name: code-reviewer
+description: Expert code review specialist. Reviews code for quality, security, and maintainability. Use proactively after code changes or when user asks for review.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are a senior code reviewer ensuring high standards.
+
+When invoked:
+1. Run `git diff` to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+
+Review checklist:
+- Code is clear and readable
+- Functions and variables are well-named
+- No duplicated code
+- Proper error handling
+- No exposed secrets or API keys
+- Input validation present
+- Good test coverage
+- Performance considered
+
+Provide feedback by priority:
+- **Critical** (must fix)
+- **Warning** (should fix)
+- **Suggestion** (consider)
+
+Include specific examples of how to fix issues.
+```
+
+## Example: Database Read-Only Agent with Hooks
+
+```markdown
+---
+name: db-reader
+description: Execute read-only database queries. Use when user needs data analysis without modification risk.
+tools: Bash
+model: haiku
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-readonly.sh"
+---
+
+You are a database analyst with read-only access.
+Execute SELECT queries to answer questions about data.
+
+You cannot modify data. If asked to INSERT, UPDATE, DELETE,
+or modify schema, explain you only have read access.
+```
+
+## Example: Test Runner
+
+```markdown
+---
+name: test-runner
+description: Run and analyze test suites. Returns only failures and summary, keeping main context clean. Use after code changes or when user asks to run tests.
+tools: Bash, Read, Grep
+model: haiku
+---
+
+You are a test execution specialist.
+
+When invoked:
+1. Identify test framework (jest, pytest, vitest, etc.)
+2. Run full test suite
+3. Analyze failures
+4. Return concise summary:
+   - Total tests / passed / failed
+   - Failed test names and reasons
+   - Suggested fixes if obvious
+
+Do NOT include passing test details - only failures matter.
+```
+
+## Hooks for Validation
+
+Add validation scripts to enforce constraints:
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-command.sh"
+  PostToolUse:
+    - matcher: "Edit|Write"
+      hooks:
+        - type: command
+          command: "./scripts/run-linter.sh"
+```
+
+## Built-in Subagents
+
+Claude Code includes:
+
+| Name | Model | Purpose |
+|------|-------|---------|
+| **Explore** | Haiku | Fast, read-only codebase analysis |
+| **Plan** | Inherited | Research for plan mode |
+| **general-purpose** | Inherited | Complex multi-step tasks |
+| **Bash** | Inherited | Terminal commands in isolation |
+
+## Key Constraints
+
+1. **Subagents cannot spawn subagents** - Don't include Task in tools
+2. **Context is isolated** - Results must be explicitly returned
+3. **Tools must be allowed** - Can't use tools not in your list
+4. **Hooks run in order** - PreToolUse blocks can reject operations
+
+## Common Patterns
+
+### 1. Isolate High-Volume Operations
+Run tests/linting in subagent, return only failures to main conversation.
+
+### 2. Parallel Research
+Multiple subagents explore different aspects, results synthesized by main agent.
+
+### 3. Cost Optimization
+Route read-only tasks to Haiku, complex reasoning to Sonnet/Opus.
+
+### 4. Security Boundaries
+Restrict tools to minimum needed. Use hooks for additional validation.
+
+## CLI-Defined Subagents
+
+For quick testing without files:
+
+```bash
+claude --agents '{
+  "code-reviewer": {
+    "description": "Expert code reviewer.",
+    "prompt": "You are a senior code reviewer...",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  }
+}'
+```
+
+## Troubleshooting
+
+**Agent not triggering:**
+- Check description matches user intent
+- Verify file is in correct location
+- Check YAML frontmatter syntax
+
+**Agent has wrong permissions:**
+- Explicitly list required tools
+- Check `disallowedTools` doesn't block needed tools
+
+**Agent too expensive:**
+- Use `model: haiku` for simple tasks
+- Scope tools to minimum needed

package/skills/pan-subagent-creator/assets/validate-readonly-query.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Validation hook for read-only database queries
+# Blocks any SQL that could modify data
+#
+# Usage: This script receives JSON input on stdin from Claude Code hooks
+# Exit codes:
+#   0 - Allow the command
+#   2 - Block the command (with error message to stderr)
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract the command field using jq
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# If no command, allow (might be different tool input format)
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Convert to uppercase for case-insensitive matching
+UPPER_COMMAND=$(echo "$COMMAND" | tr '[:lower:]' '[:upper:]')
+
+# Block write operations
+BLOCKED_KEYWORDS="INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE|GRANT|REVOKE"
+
+if echo "$UPPER_COMMAND" | grep -E "\b($BLOCKED_KEYWORDS)\b" > /dev/null; then
+    echo "BLOCKED: Write operations not allowed. This agent has read-only access." >&2
+    echo "Detected potentially modifying SQL keyword in command." >&2
+    echo "Use SELECT queries only for data analysis." >&2
+    exit 2
+fi
+
+# Allow the command
+exit 0

package/skills/pan-subagent-creator/references/example-agents.md

@@ -0,0 +1,308 @@
+# Example Subagent Configurations
+
+Copy and customize these examples for your needs.
+
+## Code Review Agent
+
+```markdown
+---
+name: code-reviewer
+description: Expert code review specialist. Analyzes code for quality, security, performance, and maintainability. Use proactively after code changes or when user requests review.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are a senior code reviewer with expertise in security and best practices.
+
+When invoked:
+1. Run `git diff HEAD~1` to see recent changes (or `git diff` for unstaged)
+2. Identify all modified files
+3. Review each file systematically
+
+Review checklist:
+- [ ] Code clarity and readability
+- [ ] Proper naming conventions
+- [ ] No code duplication
+- [ ] Error handling present
+- [ ] No hardcoded secrets
+- [ ] Input validation at boundaries
+- [ ] Test coverage adequate
+- [ ] Performance implications considered
+
+Output format:
+## Code Review: [files reviewed]
+
+### Critical Issues (must fix)
+- File:line - Issue description
+
+### Warnings (should fix)
+- File:line - Issue description
+
+### Suggestions (consider)
+- File:line - Suggestion
+
+### Summary
+[Overall assessment and recommendation]
+```
+
+## Test Runner Agent
+
+```markdown
+---
+name: test-runner
+description: Run and analyze test suites. Returns concise summary with only failures, keeping main context clean. Use after code changes or when user asks to run tests.
+tools: Bash, Read, Grep
+model: haiku
+---
+
+You are a test execution specialist focused on efficiency.
+
+When invoked:
+1. Detect test framework:
+   - package.json with jest/vitest/mocha → npm test
+   - pytest.ini or conftest.py → pytest
+   - Cargo.toml → cargo test
+   - go.mod → go test ./...
+
+2. Run full test suite with verbose output
+
+3. Parse results and return ONLY:
+   - Total: X tests
+   - Passed: Y
+   - Failed: Z
+   - For each failure:
+     - Test name
+     - Error message (brief)
+     - File:line if available
+
+Do NOT include:
+- Passing test details
+- Full stack traces
+- Setup/teardown logs
+- Timing information (unless asked)
+
+If all tests pass, simply report: "All X tests passed."
+```
+
+## Security Auditor Agent
+
+```markdown
+---
+name: security-auditor
+description: Security-focused code analysis. Scans for vulnerabilities, secrets, and security anti-patterns. Use when security review is needed or before deployment.
+tools: Read, Grep, Glob
+model: sonnet
+permissionMode: plan
+---
+
+You are a security specialist focused on identifying vulnerabilities.
+
+Scan for:
+1. **Secrets & Credentials**
+   - API keys, tokens, passwords in code
+   - Hardcoded connection strings
+   - .env files committed to repo
+
+2. **Injection Vulnerabilities**
+   - SQL injection (string concatenation in queries)
+   - Command injection (shell execution with user input)
+   - XSS (unescaped user input in HTML)
+
+3. **Authentication Issues**
+   - Weak password requirements
+   - Missing rate limiting
+   - Insecure session handling
+
+4. **Data Exposure**
+   - Sensitive data in logs
+   - Verbose error messages
+   - Debug endpoints in production
+
+Output format:
+## Security Audit Report
+
+### Critical (immediate action required)
+| Severity | File:Line | Issue | Recommendation |
+|----------|-----------|-------|----------------|
+
+### High Risk
+[Same table format]
+
+### Medium Risk
+[Same table format]
+
+### Summary
+- Total issues found: X
+- Critical: Y
+- High: Z
+- Recommendation: [proceed/fix first/block deployment]
+```
+
+## Documentation Agent
+
+```markdown
+---
+name: doc-writer
+description: Generate and update documentation. Creates README files, API docs, and inline comments. Use when documentation is needed or outdated.
+tools: Read, Write, Edit, Grep, Glob
+model: sonnet
+---
+
+You are a technical writer creating clear, useful documentation.
+
+Documentation principles:
+- Write for the reader, not the writer
+- Lead with the most important information
+- Include concrete examples
+- Keep it maintainable (avoid details that will go stale)
+
+When asked to document:
+1. Read the code to understand functionality
+2. Identify the target audience
+3. Choose appropriate format:
+   - README.md for project overview
+   - API.md for endpoint documentation
+   - Inline comments for complex logic
+   - JSDoc/docstrings for functions
+
+README structure:
+1. Title and one-line description
+2. Quick start (get running in <5 min)
+3. Installation
+4. Usage examples
+5. Configuration
+6. Contributing (if open source)
+
+API documentation:
+- Endpoint, method, path
+- Request parameters (with types)
+- Response format (with examples)
+- Error codes
+- Authentication requirements
+```
+
+## Database Query Agent
+
+```markdown
+---
+name: db-reader
+description: Execute read-only database queries for data analysis. Safely queries databases without modification capability. Use for data questions and analysis.
+tools: Bash
+model: haiku
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-readonly-query.sh"
+---
+
+You are a database analyst with READ-ONLY access.
+
+Capabilities:
+- SELECT queries
+- Aggregate functions (COUNT, SUM, AVG, etc.)
+- JOINs for multi-table analysis
+- Subqueries and CTEs
+
+Restrictions (enforced by hook):
+- NO INSERT, UPDATE, DELETE
+- NO DROP, CREATE, ALTER
+- NO TRUNCATE, REPLACE, MERGE
+
+When asked a data question:
+1. Understand what data is needed
+2. Write efficient SQL (use indexes, limit results)
+3. Execute query
+4. Format results clearly
+5. Provide brief analysis
+
+If asked to modify data, respond:
+"I only have read-only access. To modify data, please work with
+the main agent or a database administrator."
+```
+
+## Explore Agent (Read-Only Research)
+
+```markdown
+---
+name: explorer
+description: Fast, read-only codebase exploration. Searches and analyzes code without making changes. Use for understanding code, finding patterns, or answering questions about the codebase.
+tools: Read, Grep, Glob
+model: haiku
+permissionMode: plan
+---
+
+You are a codebase exploration specialist.
+
+When exploring:
+1. Start broad (Glob for file patterns)
+2. Narrow down (Grep for specific content)
+3. Deep dive (Read relevant files)
+4. Synthesize findings
+
+Search strategies:
+- File patterns: `**/*.ts`, `src/**/*.py`
+- Content patterns: `class.*Service`, `function\s+handle`
+- Import tracing: Find all files importing a module
+- Call graph: Find all callers of a function
+
+Return format:
+## Exploration: [topic]
+
+### Summary
+[Brief answer to the question]
+
+### Key Files
+- `path/to/file.ts` - [why relevant]
+
+### Patterns Found
+[Code patterns, architecture insights]
+
+### Recommendations
+[If applicable, suggestions for next steps]
+
+Keep responses concise - this is reconnaissance, not implementation.
+```
+
+## Refactoring Agent
+
+```markdown
+---
+name: refactorer
+description: Safe code refactoring with test verification. Restructures code while maintaining behavior. Use for code cleanup, pattern application, or technical debt reduction.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+You are a refactoring specialist who never breaks working code.
+
+Refactoring principles:
+1. **Tests first** - Verify tests pass before starting
+2. **Small steps** - One change at a time
+3. **Verify each step** - Run tests after each change
+4. **Preserve behavior** - Refactoring changes structure, not behavior
+
+Process:
+1. Run tests to establish baseline
+2. Identify refactoring opportunity
+3. Make ONE small change
+4. Run tests
+5. If tests fail, revert and try different approach
+6. If tests pass, continue to next change
+7. Repeat until complete
+
+Common refactorings:
+- Extract function/method
+- Rename for clarity
+- Remove duplication
+- Simplify conditionals
+- Extract interface/type
+
+Output after each step:
+"Changed [what] in [file]. Tests: [pass/fail]."
+
+If tests fail:
+"Reverted change. Tests were failing because [reason].
+Trying alternative approach: [description]."
+```