panopticon-cli 0.4.6 → 0.4.7

package/skills/pan-code-review/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: pan-code-review
+description: Orchestrated parallel code review with automatic synthesis
+triggers:
+  - code review
+  - review code
+  - pan code review
+  - parallel review
+allowed-tools:
+  - Task
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+---
+
+# Pan Code Review
+
+Orchestrates a comprehensive parallel code review using specialized review agents with automatic synthesis of findings.
+
+## Overview
+
+This skill coordinates three specialized review agents working in parallel:
+- **Correctness Reviewer** - Logic errors, edge cases, type safety
+- **Security Reviewer** - OWASP Top 10, vulnerabilities
+- **Performance Reviewer** - Algorithms, N+1 queries, memory issues
+
+After all three complete, a **Synthesis Agent** combines their findings into a unified, prioritized report.
+
+## When to Use
+
+Use this skill when you need a thorough code review:
+- Before merging a pull request
+- After implementing a new feature
+- When refactoring critical code
+- For security-sensitive changes
+- When performance matters
+
+## How It Works
+
+```
+User invokes /pan-code-review
+    ↓
+Determine scope (git diff, files, or pattern)
+    ↓
+Create .claude/reviews/ directory
+    ↓
+Spawn 3 parallel reviewers via Task tool:
+    ├─→ correctness → writes .claude/reviews/<timestamp>-correctness.md
+    ├─→ security    → writes .claude/reviews/<timestamp>-security.md
+    └─→ performance → writes .claude/reviews/<timestamp>-performance.md
+    ↓
+Wait for all 3 to complete
+    ↓
+Spawn synthesis agent
+    ↓
+Synthesis reads all 3 reviews
+    ↓
+Synthesis writes .claude/reviews/<timestamp>-synthesis.md
+    ↓
+Present unified report to user
+```
+
+## Usage
+
+### Review Uncommitted Changes
+
+```bash
+# Review all uncommitted changes (git diff)
+/pan-code-review
+
+# Same as above
+/pan-code-review --scope diff
+```
+
+### Review Specific Files
+
+```bash
+# Review specific files
+/pan-code-review --files "src/auth/*.ts"
+
+# Review a single file
+/pan-code-review --files "src/auth/auth-service.ts"
+
+# Review multiple patterns
+/pan-code-review --files "src/auth/*.ts,src/models/User.ts"
+```
+
+### Review a Branch
+
+```bash
+# Review all changes in current branch vs main
+/pan-code-review --branch main
+
+# Review vs specific branch
+/pan-code-review --branch develop
+```
+
+### Review Options
+
+```bash
+# Focus on security only
+/pan-code-review --focus security
+
+# Focus on performance only
+/pan-code-review --focus performance
+
+# Focus on correctness only
+/pan-code-review --focus correctness
+
+# Skip synthesis (get raw reviews)
+/pan-code-review --no-synthesis
+```
+
+## Implementation Guide
+
+When this skill is invoked, you should:
+
+### Step 1: Determine Scope
+
+Parse user options or use defaults:
+
+```typescript
+// Default: review uncommitted changes
+const scope = options.scope || 'diff';
+
+if (scope === 'diff') {
+  // Get uncommitted changes
+  Bash: git diff --name-only
+}
+
+if (options.files) {
+  // Use provided file pattern
+  Glob: pattern=options.files
+}
+
+if (options.branch) {
+  // Get changes vs branch
+  Bash: git diff ${options.branch}...HEAD --name-only
+}
+```
+
+### Step 2: Prepare Review Environment
+
+```typescript
+// Create reviews directory
+Bash: mkdir -p .claude/reviews
+
+// Generate timestamp for this review session
+const timestamp = new Date().toISOString().replace(/:/g, '-').split('.')[0];
+// Example: 2026-01-20T15-30-00
+```
+
+### Step 3: Launch Parallel Reviewers
+
+**IMPORTANT:** Spawn all three reviewers in a SINGLE message with multiple Task calls:
+
+```typescript
+// Spawn all 3 reviewers in parallel
+Task({
+  subagent_type: 'code-review-correctness',
+  description: 'Review code correctness',
+  prompt: `Review the following files for logic errors, edge cases, and type safety:
+
+Files to review:
+${fileList}
+
+Write your findings to: .claude/reviews/${timestamp}-correctness.md
+
+Follow the output format specified in your agent instructions.`
+});
+
+Task({
+  subagent_type: 'code-review-security',
+  description: 'Review code security',
+  prompt: `Review the following files for security vulnerabilities (OWASP Top 10):
+
+Files to review:
+${fileList}
+
+Write your findings to: .claude/reviews/${timestamp}-security.md
+
+Follow the output format specified in your agent instructions.`
+});
+
+Task({
+  subagent_type: 'code-review-performance',
+  description: 'Review code performance',
+  prompt: `Review the following files for performance issues:
+
+Files to review:
+${fileList}
+
+Write your findings to: .claude/reviews/${timestamp}-performance.md
+
+Follow the output format specified in your agent instructions.`
+});
+```
+
+### Step 4: Wait for Completion
+
+The Task tool is blocking - it waits for each agent to complete. Since you made 3 Task calls, all three will run in parallel and you'll get results when all complete.
+
+### Step 5: Spawn Synthesis Agent
+
+```typescript
+Task({
+  subagent_type: 'code-review-synthesis',
+  description: 'Synthesize review findings',
+  prompt: `Combine the findings from the three parallel code reviews.
+
+Review files to read:
+- .claude/reviews/${timestamp}-correctness.md
+- .claude/reviews/${timestamp}-security.md
+- .claude/reviews/${timestamp}-performance.md
+
+Write your synthesis to: .claude/reviews/${timestamp}-synthesis.md
+
+Provide a complete, prioritized report combining all findings.`
+});
+```
+
+### Step 6: Present Results
+
+```typescript
+// Read the synthesis report
+Read: file_path=`.claude/reviews/${timestamp}-synthesis.md`
+
+// Display to user
+console.log("Code Review Complete!");
+console.log("");
+console.log("Individual Reviews:");
+console.log(`  - Correctness: .claude/reviews/${timestamp}-correctness.md`);
+console.log(`  - Security:    .claude/reviews/${timestamp}-security.md`);
+console.log(`  - Performance: .claude/reviews/${timestamp}-performance.md`);
+console.log("");
+console.log("Unified Report:");
+console.log(`  - Synthesis:   .claude/reviews/${timestamp}-synthesis.md`);
+console.log("");
+
+// Display synthesis executive summary
+[Display key findings from synthesis]
+```
+
+## Example Session
+
+```
+User: /pan-code-review --files "src/auth/*.ts"

package/skills/pan-config/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: pan-config
+description: View and edit Panopticon configuration
+triggers:
+  - pan config
+  - panopticon config
+  - configure panopticon
+  - panopticon settings
+  - edit panopticon config
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+---
+
+# Panopticon Configuration
+
+## Overview
+
+This skill guides you through viewing and editing Panopticon configuration. Configuration is stored in `~/.panopticon/config.toml` and `~/.panopticon.env`.
+
+## When to Use
+
+- User wants to view current configuration
+- User needs to change settings (sync targets, backup options, etc.)
+- User wants to configure API keys or tokens
+- User needs to set up tracker integration
+
+## Configuration Files
+
+| File | Purpose | Format |
+|------|---------|--------|
+| `~/.panopticon/config.toml` | Main configuration | TOML |
+| `~/.panopticon.env` | API keys and secrets | ENV |
+| `~/.panopticon/projects.json` | Registered projects | JSON |
+| `~/.panopticon/project-mappings.json` | Tracker → project mappings | JSON |
+
+## View Current Configuration
+
+```bash
+# View main config
+cat ~/.panopticon/config.toml
+
+# View environment/secrets (careful - contains API keys)
+cat ~/.panopticon.env
+
+# View registered projects
+cat ~/.panopticon/projects.json
+
+# View project mappings
+cat ~/.panopticon/project-mappings.json
+```
+
+## Configuration Options
+
+### Main Config (~/.panopticon/config.toml)
+
+```toml
+[sync]
+# Which AI tools to sync skills to
+targets = ["claude", "codex", "cursor", "gemini"]
+
+# Create backup before syncing
+backup_before_sync = true
+
+[dashboard]
+# Dashboard port (default: 3010)
+port = 3010
+
+# API port (default: 3011)
+api_port = 3011
+
+[agent]
+# Default model for agents
+default_model = "sonnet"
+
+# Default runtime
+default_runtime = "claude"
+
+# Health check interval (seconds)
+health_check_interval = 30
+```
+
+### Environment Variables (~/.panopticon.env)
+
+```bash
+# Linear API key (for issue tracking)
+LINEAR_API_KEY=lin_api_xxxxx
+
+# GitHub configuration
+GITHUB_TOKEN=ghp_xxxxx
+GITHUB_REPOS=owner/repo:PREFIX,owner/repo2:PREFIX2
+GITHUB_LOCAL_PATHS=owner/repo=/path/to/local,owner/repo2=/path2
+
+# Optional: GitLab configuration
+GITLAB_TOKEN=glpat-xxxxx
+GITLAB_URL=https://gitlab.com
+```
+
+## Common Configuration Tasks
+
+### Add a New Sync Target
+
+```bash
+# Edit config.toml and add to targets array
+# Valid targets: claude, codex, cursor, gemini
+```
+
+### Configure Linear Integration
+
+```bash
+# Get your Linear API key from:
+# Settings → API → Personal API keys → Create key
+
+# Add to ~/.panopticon.env:
+echo "LINEAR_API_KEY=lin_api_your_key_here" >> ~/.panopticon.env
+```
+
+### Configure GitHub Integration
+
+```bash
+# Get token: gh auth token
+# Or create at: Settings → Developer settings → Personal access tokens
+
+# Add to ~/.panopticon.env:
+cat >> ~/.panopticon.env << 'EOF'
+GITHUB_TOKEN=your_token_here
+GITHUB_REPOS=owner/repo:PREFIX
+GITHUB_LOCAL_PATHS=owner/repo=/path/to/local
+EOF
+```
+
+### Change Dashboard Ports
+
+```bash
+# Edit ~/.panopticon/config.toml
+# Change port and api_port values
+# Restart dashboard: pan down && pan up
+```
+
+## Workflow
+
+1. **View current config**: `cat ~/.panopticon/config.toml`
+2. **Identify what to change**: Determine which setting needs modification
+3. **Edit the appropriate file**: Use your editor to modify
+4. **Restart services if needed**: `pan down && pan up`
+5. **Verify changes**: `pan doctor` or `pan status`
+
+## Troubleshooting
+
+**Problem:** Changes not taking effect
+**Solution:** Restart the dashboard with `pan down && pan up`
+
+**Problem:** API key not working
+**Solution:** Verify the key is correct and has proper permissions. Check `~/.panopticon.env` for typos.
+
+**Problem:** Sync targets not working
+**Solution:** Run `pan doctor` to check if target directories exist. Run `pan sync --dry-run` to preview.
+
+## Related Skills
+
+- `/pan:tracker` - Configure issue tracker integration
+- `/pan:projects` - Manage registered projects
+- `/pan:sync` - Sync skills to AI tools

package/skills/pan-convoy-synthesis/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: pan-convoy-synthesis
+description: Synthesize results from parallel agent work in a convoy
+triggers:
+  - convoy synthesis
+  - synthesize convoy
+  - merge convoy results
+  - convoy complete
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Task
+---
+
+# Convoy Synthesis
+
+Synthesize and integrate work from multiple agents that ran in parallel as a convoy.
+
+## When to Use
+
+Use this skill when:
+- A convoy has completed and you need to merge all agent work
+- Multiple agents worked on related issues and their changes need integration
+- You need to create a comprehensive PR from parallel work
+- Resolving conflicts between parallel agent changes
+
+## Synthesis Process
+
+### Step 1: Gather Convoy Results
+
+```bash
+# Get convoy status and results
+pan convoy status <convoy-id>
+
+# List all agents in the convoy
+pan convoy status <convoy-id> | grep -A 50 "Agents"
+```
+
+### Step 2: Collect Workspace Changes
+
+For each completed agent in the convoy:
+
+```bash
+# Check each workspace for changes
+cd ~/.panopticon/workspaces/<issue-id>
+git status
+git log --oneline -10
+git diff main...HEAD
+```
+
+### Step 3: Identify Integration Points
+
+Look for:
+- **Conflicting changes** - Same files modified by multiple agents
+- **Dependent changes** - Changes that build on each other
+- **Complementary changes** - Independent changes that combine well
+
+### Step 4: Merge Strategy
+
+#### Option A: Sequential Merge (Recommended for conflicts)
+
+```bash
+# Start from main
+git checkout main
+git pull origin main
+
+# Create integration branch
+git checkout -b convoy/<convoy-id>
+
+# Merge each agent's work in order
+git merge --no-ff feature/<issue-1>
+git merge --no-ff feature/<issue-2>
+# Resolve conflicts as needed
+git merge --no-ff feature/<issue-3>
+```
+
+#### Option B: Squash Merge (Clean history)
+
+```bash
+# Create integration branch
+git checkout -b convoy/<convoy-id>
+
+# Cherry-pick or squash from each workspace
+git merge --squash feature/<issue-1>
+git commit -m "feat: integrate <issue-1> changes"
+
+git merge --squash feature/<issue-2>
+git commit -m "feat: integrate <issue-2> changes"
+```
+
+#### Option C: Octopus Merge (No conflicts)
+
+```bash
+# If there are no conflicts, merge all at once
+git checkout main
+git merge feature/<issue-1> feature/<issue-2> feature/<issue-3>
+```
+
+### Step 5: Verify Integration
+
+```bash
+# Run tests
+npm test
+
+# Run build
+npm run build
+
+# Check for type errors
+npm run typecheck
+
+# Run linter
+npm run lint
+```
+
+### Step 6: Create Synthesis Summary
+
+Generate a summary of all integrated work:
+
+```markdown
+# Convoy Synthesis: <convoy-name>
+
+## Integrated Issues
+- <issue-1>: <title>
+- <issue-2>: <title>
+- <issue-3>: <title>
+
+## Changes Summary
+### <issue-1>
+- Brief summary of changes
+- Files modified: X
+
+### <issue-2>
+- Brief summary of changes
+- Files modified: Y
+
+### <issue-3>
+- Brief summary of changes
+- Files modified: Z
+
+## Conflicts Resolved
+- `src/file.ts`: Chose <issue-1>'s approach because...
+
+## Integration Notes
+- Any special considerations
+- Dependencies between changes
+- Known issues or follow-ups needed
+
+## Testing
+- [ ] All unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+- [ ] No regressions identified
+```
+
+### Step 7: Create Pull Request
+
+```bash
+# Push integration branch
+git push origin convoy/<convoy-id>
+
+# Create PR with synthesis summary
+gh pr create \
+  --title "Convoy: <convoy-name>" \
+  --body "$(cat synthesis-summary.md)" \
+  --base main \
+  --head convoy/<convoy-id>
+```
+
+## Conflict Resolution Guidelines
+
+### Code Conflicts
+
+When two agents modified the same code:
+
+1. **Understand both changes** - Read both versions carefully
+2. **Check dependencies** - Does one change depend on the other?
+3. **Prefer composition** - Can both changes coexist?
+4. **Test thoroughly** - Run tests after each resolution
+
+### Import Conflicts
+
+```typescript
+// Agent 1 added:
+import { FeatureA } from './features';
+
+// Agent 2 added:
+import { FeatureB } from './features';
+
+// Resolution: Combine imports
+import { FeatureA, FeatureB } from './features';
+```
+
+### Schema/Type Conflicts
+
+```typescript
+// Agent 1 added field:
+interface User {
+  id: string;
+  newField1: string;
+}
+
+// Agent 2 added field:
+interface User {
+  id: string;
+  newField2: number;
+}
+
+// Resolution: Merge all fields
+interface User {
+  id: string;
+  newField1: string;
+  newField2: number;
+}
+```
+
+## Automated Synthesis
+
+Use the convoy synthesis prompt generator:
+
+```bash
+# Generate synthesis prompt
+pan convoy synthesize <convoy-id>
+```
+
+This outputs a detailed prompt you can use to guide the synthesis process.
+
+## Best Practices
+
+1. **Review before merging** - Don't blindly merge; understand each change
+2. **Test incrementally** - Run tests after merging each agent's work
+3. **Document decisions** - Record why you chose specific conflict resolutions
+4. **Keep the PR focused** - If convoy scope is too large, consider splitting
+5. **Tag individual PRs** - Reference original issues in commit messages
+
+## Related Commands
+
+```bash
+# Convoy management
+pan convoy list
+pan convoy status <id>
+pan convoy synthesize <id>
+
+# Workspace management
+pan workspace list
+pan workspace remove <issue-id>
+```