claude-cli-advanced-starter-pack 1.0.16 → 1.8.0

package/templates/skills/agent-creator/skill.md

@@ -0,0 +1,335 @@
+---
+name: agent-creator
+description: Create Claude Code CLI agents (subagents) following best practices - proper Task tool configuration, agent specialization, workflow integration, and RAG-enhanced knowledge bases
+---
+
+# Agent Creator Skill
+
+Expert-level Claude Code agent creation following official Anthropic best practices.
+
+## When to Use This Skill
+
+This skill is automatically invoked when:
+
+- Creating new specialized agents/subagents
+- Designing agent workflows
+- Configuring agent tool access
+- Setting up multi-agent coordination
+
+## Agent Architecture Overview
+
+### What are Claude Code Agents?
+
+Agents (subagents) are specialized Claude instances launched via the `Task` tool to handle complex, multi-step tasks autonomously. They:
+
+- Run in isolated contexts with specific tool access
+- Execute tasks without interrupting main conversation
+- Return results upon completion
+- Can run in parallel for independent tasks
+
+### Agent Types
+
+| Agent Type | Description | Tools |
+|------------|-------------|-------|
+| `general-purpose` | Research, search, multi-step tasks | All tools |
+| `Explore` | Fast codebase exploration | All except Edit, Write |
+| `Plan` | Planning and discovery | All except Edit, Write |
+| `Bash` | Command execution specialist | Bash only |
+
+## Creating Custom Agents
+
+### Skill-Based Agents
+
+Agents defined as skills live in `.claude/skills/{skill-name}/`:
+
+```
+.claude/skills/
+  my-agent/
+    skill.md              # Main skill definition (YAML frontmatter)
+    context/              # Agent context files
+      README.md
+      patterns.md
+      examples.md
+    workflows/            # Sub-workflows
+      README.md
+      sub-task-1.md
+      sub-task-2.md
+```
+
+### skill.md Format
+
+```markdown
+---
+name: my-agent
+description: Brief description shown in skill list
+---
+
+# Agent Title
+
+Detailed agent instructions, patterns, and capabilities.
+
+## When to Use This Agent
+
+List specific scenarios when this agent should be invoked.
+
+## Capabilities
+
+- What this agent can do
+- Tools it has access to
+- Patterns it follows
+
+## Workflow
+
+Step-by-step process the agent follows.
+
+## Output Format
+
+What the agent returns upon completion.
+```
+
+## Agent Design Patterns
+
+### Pattern 1: Discovery Agent
+
+Purpose: Research and understand before implementation.
+
+```markdown
+---
+name: discovery-agent
+description: Research codebase, find patterns, gather requirements
+---
+
+# Discovery Agent
+
+## Purpose
+
+Explore the codebase to understand:
+- Existing patterns and conventions
+- File organization and structure
+- Dependencies and relationships
+- Potential impact areas
+
+## Workflow
+
+1. **Initial Search** - Use Glob/Grep to find relevant files
+2. **Deep Read** - Read key files to understand patterns
+3. **Map Dependencies** - Trace imports and relationships
+4. **Document Findings** - Summarize discoveries
+
+## Output
+
+Return a structured report:
+- Files discovered
+- Patterns identified
+- Key dependencies
+- Recommendations
+```
+
+### Pattern 2: Implementation Agent
+
+Purpose: Execute code changes with proper patterns.
+
+```markdown
+---
+name: implementation-agent
+description: Write code following project patterns and conventions
+---
+
+# Implementation Agent
+
+## Purpose
+
+Implement features following project standards:
+- Use established patterns
+- Maintain consistency
+- Add appropriate tests
+- Update documentation
+
+## Prerequisites
+
+- Discovery complete
+- Plan approved
+- Target files identified
+
+## Workflow
+
+1. **Read Target Files** - Understand current state
+2. **Apply Patterns** - Use project conventions
+3. **Implement Changes** - Write clean code
+4. **Add Tests** - Cover new functionality
+5. **Validate** - Ensure no regressions
+
+## Output
+
+Return implementation summary:
+- Files modified
+- Tests added
+- Breaking changes (if any)
+```
+
+### Pattern 3: QA Agent
+
+Purpose: Validate changes and ensure quality.
+
+```markdown
+---
+name: qa-agent
+description: Validate changes, run tests, verify patterns
+---
+
+# QA Agent
+
+## Purpose
+
+Ensure quality through:
+- Pattern compliance
+- Test coverage
+- Error handling
+- Performance impact
+
+## Workflow
+
+1. **Review Changes** - Examine modified files
+2. **Run Tests** - Execute relevant test suites
+3. **Check Patterns** - Verify convention compliance
+4. **Report Issues** - Document findings
+
+## Output
+
+Return QA report:
+- Tests passed/failed
+- Pattern violations
+- Recommendations
+- Sign-off status
+```
+
+### Pattern 4: Orchestrator Agent
+
+Purpose: Coordinate multiple agents for complex tasks.
+
+```markdown
+---
+name: orchestrator-agent
+description: Coordinate multi-agent workflows for complex tasks
+---
+
+# Orchestrator Agent
+
+## Purpose
+
+Coordinate complex workflows:
+- Decompose tasks
+- Assign to specialized agents
+- Aggregate results
+- Handle dependencies
+
+## Workflow
+
+1. **Analyze Task** - Understand scope
+2. **Create Plan** - Break into subtasks
+3. **Dispatch Agents** - Launch specialized agents
+4. **Monitor Progress** - Track completion
+5. **Aggregate Results** - Combine outputs
+
+## Agent Dispatch
+
+Launch agents in parallel when independent:
+- Discovery can run with initial planning
+- Implementation waits for planning
+- QA waits for implementation
+```
+
+## Task Tool Configuration
+
+### Basic Agent Launch
+
+To launch an agent, invoke the Task tool with these parameters:
+
+```json
+{
+  "description": "Research authentication patterns",
+  "prompt": "Search the codebase for authentication implementations...",
+  "subagent_type": "Explore"
+}
+```
+
+### Agent Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `description` | Yes | Short (3-5 word) task description |
+| `prompt` | Yes | Detailed task instructions |
+| `subagent_type` | Yes | Agent type to use |
+| `model` | No | Override model (sonnet, opus, haiku) |
+| `resume` | No | Agent ID to resume from |
+
+### Model Selection
+
+| Model | Best For | Cost |
+|-------|----------|------|
+| `haiku` | Quick, straightforward tasks | Lowest |
+| `sonnet` | Default, balanced | Medium |
+| `opus` | Complex reasoning | Highest |
+
+## Best Practices
+
+### Agent Design
+
+1. **Single Responsibility** - Each agent does one thing well
+2. **Clear Boundaries** - Define what agent can/cannot do
+3. **Explicit Output** - Specify return format
+4. **Error Handling** - Define failure behavior
+
+### Task Prompts
+
+1. **Be Specific** - Include all necessary context
+2. **Define Success** - What does "done" look like?
+3. **Scope Limits** - What should agent NOT do?
+4. **Output Format** - How to structure results?
+
+### Parallel Execution
+
+1. **Independence** - Only parallelize independent tasks
+2. **Single Message** - Multiple Task calls in one message
+3. **Dependencies** - Sequential tasks must wait
+
+**Parallel Execution**: In a single message, invoke the Task tool multiple times.
+
+**Sequential Execution**: For dependent tasks, wait for first agent to complete before invoking the next Task tool.
+
+### Context Management
+
+1. **Stateless** - Each agent invocation is fresh
+2. **Self-Contained** - Include all needed context in prompt
+3. **Explicit Return** - Specify what to report back
+4. **No Follow-up** - Cannot send additional messages
+
+## Creating a New Agent
+
+### Step-by-Step Process
+
+1. **Define Purpose** - What problem does this agent solve?
+2. **Identify Tools** - What tools does it need?
+3. **Design Workflow** - What steps does it follow?
+4. **Specify Output** - What does it return?
+5. **Create Skill** - Write skill.md with context
+6. **Add RAG if Needed** - Include knowledge base for domain expertise
+7. **Add to README** - Document in skills README
+8. **Test Thoroughly** - Verify in real scenarios
+
+### Checklist
+
+- [ ] skill.md with YAML frontmatter
+- [ ] Clear "When to Use" section
+- [ ] Defined workflow steps
+- [ ] Explicit output format
+- [ ] Context files if needed
+- [ ] Added to skills README
+- [ ] Tested with sample tasks
+
+## References
+
+- Task Tool: System prompt documentation
+- Skills: `.claude/skills/README.md`
+- Agents: `.claude/agents/`
+- Official Docs: https://docs.anthropic.com/en/docs/claude-code

package/templates/skills/hook-creator/skill.json

@@ -0,0 +1,18 @@
+{
+  "name": "hook-creator",
+  "version": "1.0.0",
+  "description": "Create Claude Code CLI hooks following best practices",
+  "category": "development",
+  "portability": 100,
+  "features": [
+    "JSON schema configuration",
+    "Event type handling",
+    "Matcher patterns",
+    "Error handling templates"
+  ],
+  "entryPoint": "skill.md",
+  "context": [],
+  "workflows": [],
+  "requiredTools": ["Read", "Write", "Edit"],
+  "suggestedModel": "sonnet"
+}

package/templates/skills/hook-creator/skill.md

@@ -0,0 +1,318 @@
+---
+name: hook-creator
+description: Create Claude Code CLI hooks following best practices - proper JSON schema, event types, matchers, error handling, and file organization
+---
+
+# Hook Creator Skill
+
+Expert-level Claude Code hook creation following official Anthropic best practices.
+
+## When to Use This Skill
+
+This skill is automatically invoked when:
+
+- Creating new hooks for Claude Code CLI
+- Modifying existing hook configurations
+- Writing hook scripts (JS, Python, PowerShell)
+- Configuring hook matchers and event types
+
+## Hook Architecture Overview
+
+### Configuration Files (Priority Order)
+
+1. `~/.claude/settings.json` - Global user settings (all projects)
+2. `.claude/settings.json` - Project settings (checked into git)
+3. `.claude/settings.local.json` - Local overrides (gitignored)
+
+### Hook Directory Structure
+
+```
+.claude/
+  settings.local.json        # Hook configurations (JSON)
+  hooks/
+    README.md                 # Hook system documentation
+    lifecycle/                # SessionStart, SessionEnd, Stop hooks
+      README.md
+      session-start.js
+    tools/                    # PreToolUse, PostToolUse hooks
+      README.md
+      validate-files.js
+    notifications/            # Notification hooks
+      README.md
+      alert-handler.js
+    security/                 # Security-focused hooks
+      README.md
+      block-dangerous-ops.js
+```
+
+## Supported Hook Events
+
+| Event | Trigger | Can Block | Primary Use Cases |
+|-------|---------|-----------|-------------------|
+| `SessionStart` | Session begins | No | Setup, notifications, load context |
+| `SessionEnd` | Session ends | No | Cleanup, save state |
+| `Stop` | Claude stops responding | No | Notifications, state saving |
+| `PreToolUse` | Before tool executes | **Yes** | Security gates, input validation |
+| `PostToolUse` | After tool completes | No | Logging, validation, sync |
+| `Notification` | Attention needed | No | Custom alerts, sounds |
+| `UserPromptSubmit` | Before prompt processes | **Yes** | Input validation |
+| `SubagentStop` | Subagent completes | No | Aggregate results |
+| `PreCompact` | Before transcript compaction | No | Archive, cleanup |
+| `PermissionRequest` | Permission dialog shown | No | Custom handling |
+
+## JSON Configuration Schema
+
+### Basic Hook Configuration
+
+```json
+{
+  "hooks": {
+    "EventType": [
+      {
+        "matcher": "pattern",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "your-command-here",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Configuration Fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `matcher` | No | string (regex) | Filter which tools/events trigger hook |
+| `hooks` | Yes | array | List of hook commands to execute |
+| `type` | Yes | `"command"` or `"prompt"` | Hook execution type |
+| `command` | For type:command | string | Shell command to execute |
+| `timeout` | No | number | Seconds before timeout (default: 60) |
+
+### Matcher Patterns
+
+```json
+// Single tool
+"matcher": "Write"
+
+// Multiple tools (regex OR)
+"matcher": "Write|Edit|MultiEdit"
+
+// MCP namespace
+"matcher": "mcp__browserbase__.*"
+
+// Specific MCP tool
+"matcher": "mcp__browserbase__browserbase_stagehand_act"
+
+// No matcher = all tools
+// Just omit the matcher field
+```
+
+## Hook Input/Output
+
+### Environment Variables (Available to Hooks)
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDE_HOOK_INPUT` | JSON string of tool input |
+| `CLAUDE_TOOL_NAME` | Name of tool being called |
+| `CLAUDE_SESSION_ID` | Unique session identifier |
+| `CLAUDE_PROJECT_PATH` | Path to project root |
+| `CLAUDE_PERMISSION_MODE` | Current permission mode |
+
+### Hook Output Format
+
+```json
+{
+  "decision": "approve",         // "approve", "block", or "ask"
+  "reason": "Optional explanation",
+  "systemMessage": "Warning to show user",
+  "updatedInput": {}             // Modified tool input
+}
+```
+
+### Exit Codes
+
+| Code | Meaning | Behavior |
+|------|---------|----------|
+| 0 | Success | Allow action to proceed |
+| 2 | Blocking error | Block action, show stderr to Claude |
+| Other | Non-blocking error | Show stderr to user, allow action |
+| Timeout | >60s (default) | Kill process, use default behavior |
+
+## Hook Templates
+
+### Template: JavaScript Tool Hook
+
+```javascript
+#!/usr/bin/env node
+
+/**
+ * Hook Name: [Description]
+ * Event: PreToolUse | PostToolUse
+ * Trigger: When [condition]
+ * Purpose: [What this hook accomplishes]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse hook input from environment
+const hookInput = JSON.parse(process.env.CLAUDE_HOOK_INPUT || '{}');
+const toolName = process.env.CLAUDE_TOOL_NAME || '';
+const projectPath = process.env.CLAUDE_PROJECT_PATH || process.cwd();
+
+async function main() {
+  try {
+    // Your validation/processing logic here
+    const shouldBlock = false; // Set based on your logic
+
+    if (shouldBlock) {
+      console.error('Blocked: [reason]');
+      process.exit(2); // Exit code 2 = blocking error
+    }
+
+    // Success - allow action
+    console.log(JSON.stringify({
+      decision: 'approve',
+      reason: 'Validation passed'
+    }));
+    process.exit(0);
+
+  } catch (error) {
+    // CRITICAL: Always default to allowing on error
+    console.error('Hook error:', error.message);
+    console.log(JSON.stringify({
+      decision: 'approve',
+      reason: `Error in hook: ${error.message}`
+    }));
+    process.exit(0);
+  }
+}
+
+main();
+```
+
+### Template: Python Security Hook
+
+```python
+#!/usr/bin/env python3
+"""
+Hook Name: [Description]
+Event: PreToolUse
+Trigger: Write|Edit|Bash
+Purpose: Block dangerous operations
+"""
+
+import json
+import os
+import sys
+
+# Parse hook input
+try:
+    hook_input = json.loads(os.environ.get('CLAUDE_HOOK_INPUT', '{}'))
+    tool_name = os.environ.get('CLAUDE_TOOL_NAME', '')
+    project_path = os.environ.get('CLAUDE_PROJECT_PATH', os.getcwd())
+except json.JSONDecodeError:
+    hook_input = {}
+    tool_name = ''
+    project_path = os.getcwd()
+
+# Dangerous patterns to block
+DANGEROUS_PATTERNS = [
+    '.env',
+    'secrets/',
+    'credentials',
+    'private_key',
+]
+
+def is_dangerous(file_path: str) -> bool:
+    """Check if file path matches dangerous patterns."""
+    return any(pattern in file_path.lower() for pattern in DANGEROUS_PATTERNS)
+
+def main():
+    try:
+        file_path = hook_input.get('file_path', '')
+
+        if is_dangerous(file_path):
+            sys.stderr.write(f"Blocked: Dangerous file pattern detected: {file_path}\n")
+            sys.exit(2)  # Exit 2 = blocking error
+
+        print(json.dumps({
+            'decision': 'approve',
+            'reason': 'File path validated'
+        }))
+        sys.exit(0)
+
+    except Exception as e:
+        # CRITICAL: Default to allowing on error
+        sys.stderr.write(f"Hook error: {str(e)}\n")
+        print(json.dumps({
+            'decision': 'approve',
+            'reason': f'Error in hook: {str(e)}'
+        }))
+        sys.exit(0)
+
+if __name__ == '__main__':
+    main()
+```
+
+## Best Practices
+
+### Performance
+
+1. **Keep hooks fast** - Target <5 seconds execution
+2. **Use timeouts** - Set appropriate timeouts for longer operations
+3. **Async when possible** - Background non-critical work
+4. **Minimize I/O** - Cache frequently accessed data
+
+### Security
+
+1. **Quote variables** - Prevent command injection
+2. **Validate inputs** - Never trust hook input blindly
+3. **Scope credentials** - Hooks run with your full environment
+4. **Block sensitive files** - Use PreToolUse to protect secrets
+
+### Error Handling
+
+1. **Always default to `approve`** - Don't block on hook errors
+2. **Log errors** - Write to stderr for debugging
+3. **Graceful degradation** - Hooks should fail safely
+4. **Test locally** - Verify hooks before deploying
+
+### Organization
+
+1. **Use subdirectories** - Group hooks by purpose
+2. **Document everything** - README.md in each directory
+3. **Consistent naming** - `{purpose}-{action}-hook.{ext}`
+4. **Version control** - Track hook changes in git
+
+## Workflows
+
+### Creating a New Hook
+
+1. **Determine event type** - Which lifecycle event triggers your hook?
+2. **Design matcher** - What tools/actions should trigger it?
+3. **Choose language** - JS for complex logic, Python for security
+4. **Write hook script** - Use templates above
+5. **Configure in settings** - Add to `.claude/settings.local.json`
+6. **Document** - Update README.md in appropriate directory
+7. **Test locally** - Run hook manually before enabling
+
+### Modifying Existing Hooks
+
+1. **Review current config** - Check `.claude/settings.local.json`
+2. **Understand impact** - What tools/events are affected?
+3. **Make changes** - Update configuration or hook script
+4. **Test thoroughly** - Verify both success and error paths
+5. **Update documentation** - Keep README.md current
+
+## References
+
+- Official Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
+- Project Hooks: `.claude/hooks/README.md`
+- Settings: `.claude/settings.local.json`

package/templates/skills/panel/skill.json

@@ -0,0 +1,18 @@
+{
+  "name": "panel",
+  "version": "1.0.0",
+  "description": "Launch CCASP Control Panel in a new terminal window",
+  "category": "utility",
+  "portability": 100,
+  "features": [
+    "Launch control panel in separate terminal",
+    "Cross-platform support (Windows/macOS/Linux)",
+    "Queue-based command injection",
+    "Single-key command selection"
+  ],
+  "entryPoint": "skill.md",
+  "context": [],
+  "workflows": [],
+  "requiredTools": ["Bash"],
+  "suggestedModel": "haiku"
+}