panopticon-cli 0.4.6 → 0.4.8

package/skills/pan-setup/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: pan-setup
+description: First-time configuration wizard for Panopticon
+triggers:
+  - configure panopticon
+  - setup panopticon
+  - panopticon configuration
+  - first time setup
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - AskUserQuestion
+---
+
+# Panopticon Setup Guide
+
+## Overview
+
+This skill guides you through the first-time configuration of Panopticon, including setting up issue trackers, adding projects, and configuring environment variables.
+
+## When to Use
+
+- First-time setup after installation
+- User wants to add a new issue tracker
+- User needs to configure API keys
+- User wants to add/remove projects
+- Reconfiguring Panopticon after moving to a new machine
+
+## Configuration File
+
+Panopticon's main configuration is stored in `~/.panopticon.env`.
+
+## Setup Workflow
+
+### Step 1: Initialize Configuration
+
+If not already done:
+
+```bash
+pan init
+```
+
+This creates `~/.panopticon.env` with default configuration.
+
+### Step 2: Configure Issue Tracker
+
+Panopticon supports Linear, GitHub, and GitLab issue trackers.
+
+#### Linear Configuration
+
+```bash
+# Edit ~/.panopticon.env and add:
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxx
+LINEAR_TEAM_ID=your-team-id
+```
+
+**Getting your Linear API key:**
+1. Go to https://linear.app/settings/api
+2. Create a new personal API key
+3. Copy the key (starts with `lin_api_`)
+
+**Finding your Linear Team ID:**
+```bash
+# After setting LINEAR_API_KEY, run:
+curl -X POST https://api.linear.app/graphql \
+  -H "Authorization: YOUR_LINEAR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"{ teams { nodes { id name } } }"}'
+```
+
+Or use the Linear web app URL: `https://linear.app/<workspace>/<team>`
+
+#### GitHub Configuration
+
+```bash
+# Edit ~/.panopticon.env and add:
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxx
+GITHUB_OWNER=your-username-or-org
+GITHUB_REPO=your-repo-name
+```
+
+**Getting your GitHub token:**
+1. Go to https://github.com/settings/tokens
+2. Generate new token (classic)
+3. Select scopes: `repo`, `workflow`
+4. Copy the token (starts with `ghp_`)
+
+#### GitLab Configuration
+
+```bash
+# Edit ~/.panopticon.env and add:
+GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx
+GITLAB_PROJECT_ID=12345678
+```
+
+**Getting your GitLab token:**
+1. Go to https://gitlab.com/-/profile/personal_access_tokens
+2. Create new token with `api` scope
+3. Copy the token (starts with `glpat-`)
+
+**Finding your GitLab project ID:**
+- Visit your project on GitLab
+- Project ID is shown under the project name
+
+### Step 3: Add Projects
+
+Add the projects you want Panopticon to manage:
+
+```bash
+# Add a project
+pan project add /home/user/projects/myapp
+
+# Verify it was added
+pan project list
+```
+
+You can add multiple projects:
+```bash
+pan project add /home/user/projects/frontend
+pan project add /home/user/projects/backend
+pan project add /home/user/projects/mobile
+```
+
+### Step 4: Configure Workspace Defaults
+
+Edit `~/.panopticon.env` to set workspace defaults:
+
+```env
+# Default workspace root (where workspaces are created)
+WORKSPACE_ROOT=~/projects/panopticon/workspaces
+
+# Default Docker template (spring-boot, react-vite, nextjs, etc.)
+DEFAULT_DOCKER_TEMPLATE=spring-boot
+
+# Enable Traefik for local domains (true/false)
+TRAEFIK_ENABLED=true
+
+# Traefik domain suffix
+TRAEFIK_DOMAIN=localhost
+```
+
+### Step 5: Configure Dashboard
+
+```env
+# Dashboard port (default: 3001)
+DASHBOARD_PORT=3001
+
+# API server port (default: 3002)
+API_PORT=3002
+
+# Enable auto-start dashboard on `pan up`
+AUTO_START_DASHBOARD=true
+```
+
+### Step 6: Configure AI Tools
+
+Panopticon syncs skills to various AI coding tools:
+
+```env
+# Claude Code skills directory
+CLAUDE_CODE_SKILLS=~/.claude/skills
+
+# Cursor skills directory (if using Cursor)
+CURSOR_SKILLS=~/.cursor/skills
+
+# Enable auto-sync after skill changes
+AUTO_SYNC_SKILLS=true
+```
+
+### Step 7: Optional - Configure Beads
+
+If using beads for issue tracking:
+
+```env
+# Beads database location
+BEADS_DB=~/.beads/panopticon.db
+
+# Enable beads integration
+BEADS_ENABLED=true
+```
+
+### Step 8: Verify Configuration
+
+```bash
+# Check that everything is configured correctly
+pan doctor
+
+# Verify projects are added
+pan project list
+
+# Test tracker connection (if Linear)
+pan work list
+```
+
+## Sample Configuration File
+
+Here's a complete example `~/.panopticon.env`:
+
+```env
+# Issue Tracker
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxx
+LINEAR_TEAM_ID=abc123
+
+# Projects (managed automatically via `pan project add`)
+# Projects are stored in ~/.panopticon/projects.json
+
+# Workspace Settings
+WORKSPACE_ROOT=~/projects/panopticon/workspaces
+DEFAULT_DOCKER_TEMPLATE=spring-boot
+TRAEFIK_ENABLED=true
+TRAEFIK_DOMAIN=localhost
+
+# Dashboard
+DASHBOARD_PORT=3001
+API_PORT=3002
+AUTO_START_DASHBOARD=true
+
+# AI Tools
+CLAUDE_CODE_SKILLS=~/.claude/skills
+AUTO_SYNC_SKILLS=true
+
+# Beads
+BEADS_DB=~/.beads/panopticon.db
+BEADS_ENABLED=true
+
+# Agent Settings
+DEFAULT_MODEL=sonnet
+MAX_PARALLEL_AGENTS=3
+
+# Logging
+LOG_LEVEL=info
+LOG_FILE=~/.panopticon/panopticon.log
+```
+
+## Interactive Setup
+
+To guide the user through configuration interactively:
+
+1. **Ask about issue tracker:**
+   - Which tracker do they use? (Linear, GitHub, GitLab)
+   - Help them get API key/token
+   - Help them find team/project ID
+
+2. **Ask about projects:**
+   - Which projects should Panopticon manage?
+   - Get absolute paths to project directories
+
+3. **Ask about Docker:**
+   - What type of projects? (Spring Boot, React, Next.js, etc.)
+   - Set appropriate default template
+
+4. **Ask about preferences:**
+   - Should dashboard auto-start?
+   - Enable Traefik for local domains?
+   - Auto-sync skills to AI tools?
+
+## Troubleshooting
+
+### Can't connect to Linear
+
+**Problem:** `pan work list` fails with authentication error
+
+**Solutions:**
+```bash
+# Verify API key is correct
+echo $LINEAR_API_KEY  # Should start with lin_api_
+
+# Test API key directly
+curl -X POST https://api.linear.app/graphql \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"{ viewer { name } }"}'
+
+# Should return your name, not an error
+```
+
+### Projects not showing up
+
+**Problem:** `pan project list` shows no projects
+
+**Solutions:**
+```bash
+# Add project again
+pan project add /path/to/project
+
+# Check projects.json directly
+cat ~/.panopticon/projects.json
+
+# Verify path is absolute (not relative)
+pan project add "$(pwd)"  # Use $PWD for current directory
+```
+
+### Dashboard won't start
+
+**Problem:** `pan up` fails or dashboard unreachable
+
+**Solutions:**
+```bash
+# Check ports aren't in use
+lsof -i :3001
+lsof -i :3002
+
+# Check configuration
+cat ~/.panopticon.env | grep PORT
+
+# Try custom ports
+DASHBOARD_PORT=4001 API_PORT=4002 pan up
+```
+
+### Skills not syncing
+
+**Problem:** Skills don't appear in Claude Code
+
+**Solutions:**
+```bash
+# Run sync manually
+pan sync
+
+# Check target directory exists
+ls ~/.claude/skills/
+
+# Create if missing
+mkdir -p ~/.claude/skills
+
+# Verify permissions
+chmod -R u+w ~/.claude/skills
+
+# Sync again
+pan sync
+```
+
+### Environment variables not loading
+
+**Problem:** Configuration changes don't take effect
+
+**Solutions:**
+```bash
+# Verify file location
+ls -la ~/.panopticon.env
+
+# Check for syntax errors
+cat ~/.panopticon.env
+
+# Ensure no spaces around = in env vars
+# WRONG: KEY = value
+# RIGHT: KEY=value
+
+# Restart services
+pan down
+pan up
+```
+
+## What Your Project Repository Needs
+
+After adding a project, you may need to create templates in your project for Docker-based workspaces to work. **This is optional if you only need git worktrees without Docker.**
+
+### For Docker-Based Workspaces
+
+Your project needs to provide templates that Panopticon copies/processes when creating workspaces:
+
+```
+your-project/
+├── infra/
+│   └── .devcontainer-template/
+│       ├── docker-compose.devcontainer.yml.template
+│       ├── compose.infra.yml.template   # Optional: for postgres, redis, etc.
+│       ├── Dockerfile
+│       └── devcontainer.json.template   # Optional: VS Code integration
+└── ...
+```
+
+### Docker Compose Template Example
+
+```yaml
+# docker-compose.devcontainer.yml.template
+services:
+  app:
+    build: .
+    labels:
+      - "traefik.http.routers.{{FEATURE_FOLDER}}.rule=Host(`{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
+    volumes:
+      - ../..:/workspace:cached
+```
+
+**Available placeholders:**
+- `{{FEATURE_NAME}}` - Issue ID (e.g., `min-123`)
+- `{{FEATURE_FOLDER}}` - Workspace folder (e.g., `feature-min-123`)
+- `{{BRANCH_NAME}}` - Git branch (e.g., `feature/min-123`)
+- `{{COMPOSE_PROJECT}}` - Docker project name
+- `{{DOMAIN}}` - Configured domain (e.g., `myapp.test`)
+
+### For Database Seeding
+
+If your project uses a database:
+
+```
+your-project/
+├── infra/
+│   └── seed/
+│       └── seed.sql          # Pre-populated database dump
+└── ...
+```
+
+Mount in your compose template:
+```yaml
+services:
+  postgres:
+    image: postgres:16
+    volumes:
+      - /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro
+```
+
+### Minimal Setup (Git Worktrees Only)
+
+For simple projects that don't need Docker:
+
+```yaml
+# In ~/.panopticon/projects.yaml
+projects:
+  simple-app:
+    name: "Simple App"
+    path: /home/user/projects/simple-app
+    linear_team: APP
+    # No workspace config = uses plain git worktrees
+```
+
+### Full Configuration
+
+See README section "What Your Project Needs to Provide" for complete documentation:
+https://github.com/eltmon/panopticon#what-your-project-needs-to-provide
+
+---
+
+## Post-Setup
+
+After configuration:
+
+1. **Start services**: `pan up`
+2. **Verify health**: `pan doctor`
+3. **Test issue tracker**: `pan work list`
+4. **Sync skills**: `pan sync`
+5. **Create first workspace**: Use `/pan-issue` skill
+
+## Configuration Checklist
+
+- [ ] Run `pan init` to create config file
+- [ ] Add issue tracker API key (Linear/GitHub/GitLab)
+- [ ] Add at least one project with `pan project add`
+- [ ] Set workspace defaults (root directory, Docker template)
+- [ ] Configure dashboard ports if needed
+- [ ] Enable AI tools sync
+- [ ] Run `pan doctor` to verify
+- [ ] Run `pan work list` to test tracker connection
+- [ ] Run `pan sync` to distribute skills
+- [ ] Start dashboard with `pan up`
+
+## Next Steps
+
+- Use `/pan-quickstart` for combined install + setup workflow
+- Use `/pan-docker` to configure Docker templates
+- Use `/pan-tracker` for advanced tracker configuration
+- Use `/pan-help` to explore available commands
+
+## Related Skills
+
+- `/pan-install` - Installation prerequisites
+- `/pan-quickstart` - Quick start guide
+- `/pan-tracker` - Tracker configuration (advanced)
+- `/pan-projects` - Project management
+- `/pan-config` - View/edit configuration
+
+## More Information
+
+- Configuration file: `~/.panopticon.env`
+- Projects list: `~/.panopticon/projects.json`
+- Run `pan doctor` to check configuration
+- Visit dashboard at http://localhost:3001

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

@@ -0,0 +1,168 @@
+---
+name: pan-skill-creator
+description: Create effective Claude Code skills with specialized knowledge, workflows, and tools. Use when users want to create a new skill, update an existing skill, learn skill best practices, or extend Claude's capabilities. Triggers on "create a skill", "make a new skill", "skill development", "build a skill", or "extend capabilities".
+---
+
+# Skill Creator
+
+Create skills that transform Claude from general-purpose into a specialized agent with procedural knowledge.
+
+## Core Principles
+
+### 1. Concise is Key
+The context window is shared. Claude is already very smart - only add what Claude doesn't already know. Challenge each piece: "Does this justify its token cost?"
+
+### 2. Degrees of Freedom
+Match specificity to task fragility:
+
+| Freedom Level | When to Use | Format |
+|---------------|-------------|--------|
+| **High** | Multiple valid approaches, context-dependent | Text instructions |
+| **Medium** | Preferred pattern exists, some variation OK | Pseudocode, parameterized scripts |
+| **Low** | Fragile operations, consistency critical | Specific scripts, few parameters |
+
+### 3. Progressive Disclosure
+Three-level loading system:
+1. **Metadata** (~100 words) - Always in context
+2. **SKILL.md body** (<5k words) - When skill triggers
+3. **Bundled resources** - As needed (unlimited)
+
+## Skill Anatomy
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description - REQUIRED)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/     - Executable code (deterministic, reusable)
+    ├── references/  - Documentation loaded into context as needed
+    └── assets/      - Files used in output (templates, images)
+```
+
+### Frontmatter (Critical)
+
+```yaml
+---
+name: my-skill
+description: What it does AND when to use it. This is the ONLY thing Claude sees to decide if the skill triggers. Be comprehensive but under 200 chars.
+---
+```
+
+**Strong descriptions include:**
+- Specific verbs (extract, create, merge, validate)
+- Concrete use cases
+- Explicit boundaries ("Not for X")
+- Trigger phrases users might say
+
+### Bundled Resources
+
+| Directory | Purpose | When to Include |
+|-----------|---------|-----------------|
+| `scripts/` | Python/Bash automation | Same code rewritten repeatedly OR deterministic reliability needed |
+| `references/` | Docs, schemas, APIs | Large documentation Claude should reference while working |
+| `assets/` | Templates, images, fonts | Files used in output but not loaded into context |
+
+Use `{baseDir}` for portable paths: `{baseDir}/scripts/helper.py`
+
+### What NOT to Include
+- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
+- Setup/testing procedures for humans
+- User-facing documentation
+- Anything not needed by the AI agent
+
+## Creation Process
+
+### Step 1: Understand with Examples
+Ask:
+- "What functionality should this skill support?"
+- "Can you give examples of how it would be used?"
+- "What would a user say that should trigger this?"
+
+### Step 2: Plan Reusable Contents
+For each example, identify:
+- Scripts for repetitive code
+- References for documentation/schemas
+- Assets for templates/boilerplate
+
+### Step 3: Initialize Structure
+```bash
+mkdir -p skill-name/{scripts,references,assets}
+touch skill-name/SKILL.md
+```
+
+### Step 4: Implement
+
+**Writing guidelines:**
+- Always use imperative form ("Do X", not "You should do X")
+- Keep SKILL.md under 500 lines
+- Test scripts by actually running them
+- Delete unused example directories
+
+**Organize by domain for multi-domain skills:**
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── references/
+    ├── finance.md
+    ├── sales.md
+    └── product.md
+```
+
+### Step 5: Test
+
+| Test Type | What to Verify |
+|-----------|----------------|
+| Normal operations | Typical requests handled correctly |
+| Edge cases | Graceful handling of incomplete/unusual inputs |
+| Out-of-scope | Skill stays dormant on related but distinct tasks |
+| Triggering | Activation on explicit and natural requests |
+
+### Step 6: Iterate
+Use skill on real tasks → Notice struggles → Update → Test again
+
+## Common Patterns
+
+### Pattern 1: High-level guide with conditional references
+```markdown
+# PDF Processing
+
+## Quick start
+[Basic example]
+
+## Advanced features
+- **Form filling**: See references/FORMS.md for complete guide
+- **API reference**: See references/REFERENCE.md for all methods
+```
+
+### Pattern 2: Script automation
+```markdown
+## Rotate PDF
+Run the rotation script:
+\`\`\`bash
+python {baseDir}/scripts/rotate_pdf.py --input "$FILE" --degrees 90
+\`\`\`
+```
+
+### Pattern 3: Wizard workflow
+Break complex tasks into discrete steps with user confirmation gates between phases.
+
+## Tool Permissions (Advanced)
+
+Scope tool access for security:
+```yaml
+allowed-tools: "Bash(git status:*),Bash(git diff:*),Read,Grep"
+```
+
+## Key Takeaways
+
+1. **Description is everything** - Primary triggering mechanism
+2. **Be concise** - Every token costs context space
+3. **Use progressive disclosure** - Load detail only when needed
+4. **Write for another Claude** - Procedural knowledge that wouldn't be obvious
+5. **Test triggering** - Verify activation on intended requests
+6. **Iterate** - Refine based on real usage
+
+## Reference Files
+- See `references/workflows.md` for multi-step process patterns
+- See `references/output-patterns.md` for output format patterns