@torka/claude-workflows 0.1.0

package/install.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * @torka/claude-workflows - Post-install script
+ * Copies workflow files to the appropriate .claude directory
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ANSI colors for output
+const colors = {
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function logSuccess(message) {
+  log(`  ✓ ${message}`, 'green');
+}
+
+function logSkip(message) {
+  log(`  ○ ${message}`, 'yellow');
+}
+
+function logError(message) {
+  log(`  ✗ ${message}`, 'red');
+}
+
+/**
+ * Determine the target .claude directory based on installation context
+ */
+function getTargetBase() {
+  // Check if this is a global installation
+  const isGlobal = process.env.npm_config_global === 'true';
+
+  if (isGlobal) {
+    // Global install: use ~/.claude
+    return path.join(os.homedir(), '.claude');
+  }
+
+  // Local install: find the project root (where package.json lives)
+  // Start from INIT_CWD (where npm was run) or current working directory
+  let projectRoot = process.env.INIT_CWD || process.cwd();
+
+  // Walk up to find package.json (the actual project, not this package)
+  while (projectRoot !== path.dirname(projectRoot)) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      // Make sure it's not our own package.json
+      try {
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        if (pkg.name !== '@torka/claude-workflows') {
+          return path.join(projectRoot, '.claude');
+        }
+      } catch (e) {
+        // Continue walking up
+      }
+    }
+    projectRoot = path.dirname(projectRoot);
+  }
+
+  // Fallback to INIT_CWD
+  return path.join(process.env.INIT_CWD || process.cwd(), '.claude');
+}
+
+/**
+ * Recursively copy directory contents
+ */
+function copyDirRecursive(src, dest, stats) {
+  if (!fs.existsSync(src)) {
+    return;
+  }
+
+  // Create destination directory if it doesn't exist
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, stats);
+    } else {
+      if (fs.existsSync(destPath)) {
+        stats.skipped.push(destPath);
+        logSkip(`Skipped (exists): ${path.relative(stats.targetBase, destPath)}`);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+        stats.copied.push(destPath);
+        logSuccess(`Copied: ${path.relative(stats.targetBase, destPath)}`);
+      }
+    }
+  }
+}
+
+/**
+ * Main installation function
+ */
+function install() {
+  const packageDir = __dirname;
+  const targetBase = getTargetBase();
+  const isGlobal = process.env.npm_config_global === 'true';
+
+  log('\n' + colors.bold + '📦 @torka/claude-workflows - Installing...' + colors.reset);
+  log(`   Target: ${targetBase}`, 'blue');
+  log(`   Mode: ${isGlobal ? 'Global' : 'Project-level'}\n`, 'blue');
+
+  // Create target .claude directory if it doesn't exist
+  if (!fs.existsSync(targetBase)) {
+    fs.mkdirSync(targetBase, { recursive: true });
+  }
+
+  const stats = {
+    copied: [],
+    skipped: [],
+    targetBase,
+  };
+
+  // Define what to copy and where
+  const mappings = [
+    { src: 'commands', dest: 'commands' },
+    { src: 'agents', dest: 'agents' },
+    { src: 'skills', dest: 'skills' },
+    { src: 'hooks', dest: 'scripts' },  // Hooks go to scripts directory
+    { src: 'scripts', dest: 'scripts' },
+  ];
+
+  for (const { src, dest } of mappings) {
+    const srcPath = path.join(packageDir, src);
+    const destPath = path.join(targetBase, dest);
+
+    if (fs.existsSync(srcPath)) {
+      log(`\n${colors.bold}${src}/${colors.reset}`);
+      copyDirRecursive(srcPath, destPath, stats);
+    }
+  }
+
+  // Summary
+  log('\n' + colors.bold + '📊 Installation Summary' + colors.reset);
+  log(`   Files copied: ${stats.copied.length}`, 'green');
+  log(`   Files skipped (already exist): ${stats.skipped.length}`, 'yellow');
+
+  // Post-install instructions
+  log('\n' + colors.bold + '📝 Next Steps' + colors.reset);
+  log('   1. Configure hooks in .claude/settings.local.json');
+  log('   2. See examples/settings.local.example.json for configuration');
+  log('   3. Run /git-cleanup-and-merge or /plan-parallelization to test\n');
+
+  // Note about BMAD dependencies
+  log(colors.yellow + '⚠️  Note: Some components require BMAD Method workflows:' + colors.reset);
+  log('   - implement-epic-with-subagents');
+  log('   - principal-code-reviewer');
+  log('   - story-prep-master');
+  log('\n   Standalone components work without dependencies:');
+  log('   ✓ git-cleanup-and-merge');
+  log('   ✓ plan-parallelization');
+  log('   ✓ agent-creator skill');
+  log('   ✓ auto_approve_safe hook');
+  log('   ✓ context-monitor status line\n');
+}
+
+// Run installation
+try {
+  install();
+} catch (error) {
+  logError(`Installation failed: ${error.message}`);
+  // Don't exit with error code - allow npm install to complete
+  console.error(error);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@torka/claude-workflows",
+  "version": "0.1.0",
+  "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, hooks, and status line",
+  "keywords": [
+    "claude-code",
+    "ai-workflows",
+    "developer-tools",
+    "automation",
+    "git-management",
+    "code-review",
+    "claude",
+    "anthropic"
+  ],
+  "author": "Varun Torka",
+  "license": "MIT",
+  "homepage": "https://github.com/varuntorka/vt-claude-workflows#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/varuntorka/vt-claude-workflows.git"
+  },
+  "bugs": {
+    "url": "https://github.com/varuntorka/vt-claude-workflows/issues"
+  },
+  "scripts": {
+    "postinstall": "node install.js",
+    "preuninstall": "node uninstall.js"
+  },
+  "files": [
+    "commands",
+    "agents",
+    "skills",
+    "hooks",
+    "scripts",
+    "examples",
+    ".claude-plugin",
+    "install.js",
+    "uninstall.js",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "bmad-method": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "bmad-method": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/scripts/context-monitor.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Claude Code Context Monitor
+Real-time context usage monitoring with visual indicators and session analytics
+https://code.claude.com/docs/en/statusline
+"""
+
+import json
+import sys
+import os
+
+
+def context_window_info(window):
+    """
+    Build context info from the statusline `context_window` payload.
+    Expected shape:
+    {
+        "context_window_size": int,
+        "current_usage": {
+            "input_tokens": int,
+            "output_tokens": int,
+            "cache_creation_input_tokens": int,
+            "cache_read_input_tokens": int
+        }
+    }
+    """
+    if not isinstance(window, dict):
+        return None
+
+    size = window.get("context_window_size")
+    if not size or size <= 0:
+        return None
+
+    usage = window.get("current_usage")
+
+    # If no calls yet, usage may be null; treat as 0% used.
+    if usage is None:
+        return {
+            "percent": 0,
+            "tokens": 0,
+            "method": "context_window",
+        }
+
+    if not isinstance(usage, dict):
+        return None
+
+    tokens = (
+        usage.get("input_tokens", 0)
+        + usage.get("output_tokens", 0)
+        + usage.get("cache_creation_input_tokens", 0)
+        + usage.get("cache_read_input_tokens", 0)
+    )
+
+    percent = (tokens / size) * 100 if size > 0 else 0
+
+    return {
+        "percent": max(0, min(100, percent)),
+        "tokens": tokens,
+        "method": "context_window",
+    }
+
+
+def get_context_display(context_info):
+    """Generate context display with visual indicators."""
+    if not context_info:
+        return "🔵 ???"
+    
+    percent = context_info.get('percent', 0)
+    percent = max(0, min(100, percent))
+    warning = context_info.get('warning')
+    
+    # Color based on usage level
+    if percent >= 95:
+        color = "\033[31;1m"  # Blinking red
+        alert = "CRIT"
+    elif percent >= 90:
+        color = "\033[31m"    # Red
+        alert = "HIGH"
+    elif percent >= 75:
+        color = "\033[91m"    # Light red
+        alert = ""
+    elif percent >= 50:
+        color = "\033[33m"    # Yellow
+        alert = ""
+    else:
+        color = "\033[32m"    # Green
+        alert = ""
+    
+    # Create progress bar
+    segments = 8
+    filled = int((percent / 100) * segments)
+    bar = "█" * filled + "▁" * (segments - filled)
+    
+    # Special warnings
+    if warning == 'auto-compact':
+        alert = "AUTO-COMPACT!"
+    elif warning == 'low':
+        alert = "LOW!"
+    
+    reset = "\033[0m"
+    alert_str = f" {alert}" if alert else ""
+    
+    return f"{color}{bar}{reset} {percent:.0f}%{alert_str}"
+
+def get_directory_display(workspace_data):
+    """Get directory display name."""
+    current_dir = workspace_data.get('current_dir', '')
+    project_dir = workspace_data.get('project_dir', '')
+    cwd = workspace_data.get('cwd', '')
+
+    if current_dir and project_dir:
+        if current_dir.startswith(project_dir):
+            rel_path = current_dir[len(project_dir):].lstrip('/')
+            return rel_path or os.path.basename(project_dir)
+        else:
+            return os.path.basename(current_dir)
+    elif project_dir:
+        return os.path.basename(project_dir)
+    elif cwd:
+        return os.path.basename(cwd)
+    elif current_dir:
+        return os.path.basename(current_dir)
+    else:
+        return "unknown"
+
+def get_git_branch():
+    """Get the current git branch name by reading .git/HEAD directly."""
+    try:
+        git_dir = ".git"
+        if os.path.isdir(git_dir):
+            head_file = os.path.join(git_dir, "HEAD")
+            if os.path.isfile(head_file):
+                with open(head_file, 'r') as f:
+                    ref = f.read().strip()
+                    if ref.startswith('ref: refs/heads/'):
+                        return ref.replace('ref: refs/heads/', '')
+                    # Detached HEAD state
+                    return ref[:8]
+        return None
+    except Exception:
+        return None
+
+def main():
+    try:
+        # Read JSON input from Claude Code
+        data = json.load(sys.stdin)
+        
+        # Extract information
+        model_data = data.get('model', {})
+        model_name = model_data.get('display_name') or model_data.get('name') or model_data.get('id') or 'Claude'
+        model_id = model_data.get('id') or model_data.get('name') or model_name
+
+        workspace = data.get('workspace', {})
+        context_window = data.get('context_window') or {}
+
+        # Build status components
+        context_info = context_window_info(context_window)
+        context_display = get_context_display(context_info)
+        directory = get_directory_display(workspace)
+        git_branch = get_git_branch()
+        git_display = f" \033[96m🌿 {git_branch}\033[0m" if git_branch else ""
+
+        model_display = f"\033[94m[{model_name}]\033[0m"
+
+        # Combine all components
+        status_line = f"{model_display} \033[93m📁 {directory}\033[0m{git_display} 🧠 {context_display}"
+        
+        print(status_line)
+        
+    except Exception as e:
+        # Fallback display on any error
+        print(f"\033[94m[Claude]\033[0m \033[93m📁 {os.path.basename(os.getcwd())}\033[0m 🧠 \033[31m[Error: {str(e)[:20]}]\033[0m")
+
+if __name__ == "__main__":
+    main()

package/skills/agent-creator/COMMUNITY-REPOS.md

@@ -0,0 +1,212 @@
+# Community Resources for Agent Patterns
+
+Reference this file when researching agent patterns in Step 3.
+
+## Research Limits
+
+**IMPORTANT: To prevent endless research loops, follow these limits:**
+
+| Activity | Maximum |
+|----------|---------|
+| GitHub repo searches | 3 queries |
+| Repos to evaluate in detail | 5 repos |
+| Web searches | 2 queries |
+| Total research time | 10 minutes |
+
+After hitting limits, proceed with the best patterns found.
+
+---
+
+## Curated Community Repositories
+
+These repositories are pre-vetted for agent/workflow patterns:
+
+### Primary Resources (Check First)
+
+| Repository | Focus Area | URL |
+|------------|------------|-----|
+| **claude-code-templates** | CLI tool components, templates | https://github.com/davila7/claude-code-templates |
+| **wshobson/agents** | Agent definitions | https://github.com/wshobson/agents |
+| **claude-flow** | Multi-agent orchestration | https://github.com/ruvnet/claude-flow |
+| **awesome-claude-code** | Curated resources | https://github.com/hesreallyhim/awesome-claude-code |
+| **SuperClaude Framework** | Enhanced agent framework | https://github.com/SuperClaude-Org/SuperClaude_Framework |
+| **compound-engineering-plugin** | Engineering workflows | https://github.com/EveryInc/compound-engineering-plugin |
+| **claude-code-workflows** | Workflow definitions | https://github.com/OneRedOak/claude-code-workflows |
+| **infrastructure-showcase** | Infrastructure patterns | https://github.com/diet103/claude-code-infrastructure-showcase |
+
+### Official Anthropic Resources
+
+| Resource | URL |
+|----------|-----|
+| Claude Code Repository | https://github.com/anthropics/claude-code |
+| Awesome Claude Code (Official) | https://github.com/anthropics/awesome-claude-code |
+| Claude Code Documentation | https://docs.anthropic.com/en/docs/claude-code |
+
+---
+
+## Quick Lookup Commands
+
+Use these commands to quickly fetch patterns from curated repos:
+
+```bash
+# Fetch agent examples from claude-code-templates
+curl -s https://api.github.com/repos/davila7/claude-code-templates/contents/cli-tool/components | jq '.[].name'
+
+# Check SuperClaude Framework structure
+curl -s https://api.github.com/repos/SuperClaude-Org/SuperClaude_Framework/contents | jq '.[].name'
+
+# View claude-flow agents
+curl -s https://api.github.com/repos/ruvnet/claude-flow/contents | jq '.[].name'
+```
+
+---
+
+## Evaluation Criteria
+
+When evaluating repositories and patterns, score using these criteria:
+
+### Repository Quality (Score 1-5 each)
+
+| Criteria | Weight | How to Check |
+|----------|--------|--------------|
+| **Recent Activity** | High | Last commit < 30 days = 5, < 90 days = 3, > 90 days = 1 |
+| **Stars** | Medium | 100+ = 5, 50+ = 4, 20+ = 3, 10+ = 2, <10 = 1 |
+| **Documentation** | Medium | Has README with examples = 5, Basic README = 3, None = 1 |
+| **Relevance** | High | Directly applicable = 5, Needs adaptation = 3, Tangential = 1 |
+
+### Quick Activity Check
+```bash
+# Check repo stats (stars, last update)
+gh repo view {owner}/{repo} --json stargazerCount,pushedAt,description
+
+# Example:
+gh repo view ruvnet/claude-flow --json stargazerCount,pushedAt
+```
+
+### Pattern Quality (Score 1-5 each)
+
+| Criteria | What to Look For |
+|----------|------------------|
+| **Clarity** | Is the agent's purpose immediately obvious? |
+| **Specificity** | Will the description trigger correctly? |
+| **Tool Access** | Follows least-privilege principle? |
+| **Completeness** | Includes workflow steps? |
+| **Adaptability** | Can be customized for this project? |
+
+### Minimum Thresholds
+
+Only use patterns from repos that meet:
+- Last commit within 90 days OR 50+ stars
+- Clear documentation or examples
+- At least 3/5 on relevance score
+
+---
+
+## Agent Pattern Templates
+
+### Explorer Pattern
+```markdown
+---
+name: tmp-explorer
+description: Explores and understands codebases. Use when needing to understand project structure, find specific code, or map dependencies.
+tools: Read, Glob, Grep, Bash
+model: haiku
+---
+
+You are a codebase explorer. Your job is to efficiently navigate and understand code.
+
+When exploring:
+1. Start with project structure (tree, ls)
+2. Identify key files (package.json, config files)
+3. Map dependencies and relationships
+4. Report findings in structured format
+```
+
+### Implementer Pattern
+```markdown
+---
+name: tmp-implementer
+description: Implements features and writes code. Use when creating new functionality or modifying existing code.
+tools: Read, Write, Edit, Bash, Glob
+model: sonnet
+---
+
+You are a senior developer implementing features.
+
+When implementing:
+1. Understand requirements fully
+2. Check existing patterns in codebase
+3. Write clean, tested code
+4. Follow project conventions
+```
+
+### Reviewer Pattern
+```markdown
+---
+name: tmp-reviewer
+description: Reviews code for quality, security, and best practices. Use proactively after code changes.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+You are a senior code reviewer.
+
+Review checklist:
+- Code clarity and readability
+- Security vulnerabilities
+- Error handling
+- Test coverage
+- Performance concerns
+```
+
+### Tester Pattern
+```markdown
+---
+name: tmp-tester
+description: Creates and runs tests. Use when writing unit tests, integration tests, or running test suites.
+tools: Read, Write, Edit, Bash
+model: sonnet
+---
+
+You are a QA engineer writing tests.
+
+When testing:
+1. Understand the code to test
+2. Identify test cases (happy path, edge cases, errors)
+3. Write comprehensive tests
+4. Run and verify all pass
+```
+
+---
+
+## Search Strategy (If Curated Repos Insufficient)
+
+Only if the curated repos above don't have relevant patterns:
+
+### GitHub Search (Max 3 queries)
+```bash
+# Query 1: General agent search
+gh search repos "claude code agents" --sort stars --limit 5
+
+# Query 2: Specific pattern search
+gh search code "{pattern-type}" path:.claude/agents --limit 10
+
+# Query 3: Workflow search
+gh search repos "claude subagent" --sort updated --limit 5
+```
+
+### Web Search (Max 2 queries)
+- `"{specific-agent-type}" claude code github`
+- `claude code agent patterns {technology}`
+
+---
+
+## Web Resources
+
+### Documentation
+- Anthropic Docs: https://docs.anthropic.com
+- Claude Code Guide: https://code.claude.com
+
+### Community
+- Anthropic Discord: https://discord.gg/anthropic
+- GitHub Discussions: https://github.com/anthropics/claude-code/discussions

package/skills/agent-creator/NON-STORY-AGENT-TEMPLATE.md

@@ -0,0 +1,90 @@
+# Non-Story Agent Template (Rare)
+
+Only use this template when explicitly requested for non-story tasks (research, exploration, documentation, etc.).
+
+---
+
+## Full Template
+
+```markdown
+---
+name: {agent-name}
+description: {Clear description of when/why to use this agent. Be specific about triggers.}
+tools: {Comma-separated list of allowed tools}
+model: {sonnet|haiku|opus|inherit}
+---
+
+# Role & Purpose
+
+You are a {role description} specialized in {specialty}.
+
+## When to Activate
+
+This agent should be used when:
+- {Trigger condition 1}
+- {Trigger condition 2}
+
+## Core Responsibilities
+
+1. {Primary responsibility}
+2. {Secondary responsibility}
+
+## Workflow
+
+1. {First step}
+2. {Second step}
+3. {Continue as needed}
+
+## Output Format
+
+{Describe expected output structure}
+
+## Constraints
+
+- {Limitation 1}
+- {Limitation 2}
+```
+
+---
+
+## Minimal Template
+
+```markdown
+---
+name: {name}
+description: {When to use this agent}
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+You are a {role}. Your job is to {primary task}.
+
+When invoked:
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+```
+
+---
+
+## Common Non-Story Agent Patterns
+
+| Agent Type | Use Case | Key Tools |
+|------------|----------|-----------|
+| `explorer` | Codebase research, file discovery | Read, Glob, Grep |
+| `documenter` | Documentation-only updates | Read, Write |
+
+---
+
+## Validation Checklist
+
+Before saving a non-story agent, verify:
+
+1. **Name format**: `{lowercase-alphanumeric-hyphens}`
+2. **Tools list**: Only valid Claude Code tools
+3. **Model**: `sonnet`, `haiku`, `opus`, or `inherit`
+4. **Description**: 20-300 characters, specific triggers
+5. **Content includes**:
+   - Clear activation conditions
+   - Defined workflow steps
+   - Expected output format