@torka/claude-workflows 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,51 @@
+{
+  "name": "@torka/claude-workflows",
+  "version": "0.1.0",
+  "description": "Epic automation, git cleanup, code review agents, and workflow helpers for Claude Code",
+  "commands": [
+    {
+      "name": "implement-epic-with-subagents",
+      "description": "Automate entire epic execution by orchestrating sub-agents to execute all stories sequentially"
+    },
+    {
+      "name": "plan-parallelization",
+      "description": "Analyze epic files to identify which epics can run in parallel using Git worktrees"
+    },
+    {
+      "name": "git-cleanup-and-merge",
+      "description": "Analyze git branches, cleanup merged branches, push changes, create PRs, wait for CI, and merge"
+    }
+  ],
+  "agents": [
+    {
+      "name": "principal-code-reviewer",
+      "description": "Expert-level code review after completing coding tasks or stories"
+    },
+    {
+      "name": "story-prep-master",
+      "description": "Create, refine, or prepare user stories for development"
+    }
+  ],
+  "skills": [
+    {
+      "name": "agent-creator",
+      "description": "Creates custom Claude Code sub-agents for project tasks"
+    }
+  ],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "name": "auto_approve_safe",
+        "description": "Auto-approve safe tool usage for solo dev workflows",
+        "script": "auto_approve_safe.py"
+      }
+    ]
+  },
+  "scripts": {
+    "statusLine": {
+      "name": "context-monitor",
+      "description": "Real-time context usage monitoring with visual indicators",
+      "script": "context-monitor.py"
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Varun Torka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# @torka/claude-workflows
+
+Claude Code workflow helpers for epic automation, git management, and developer productivity.
+
+## Features
+
+| Feature | Description | Standalone |
+|---------|-------------|------------|
+| **Git Cleanup & Merge** | Intelligent branch management, PR creation, CI monitoring | Yes |
+| **Parallelization Analysis** | Identify which epics can run in parallel with Git worktrees | Yes |
+| **Agent Creator** | Design and deploy custom Claude Code agents | Yes |
+| **Auto-Approve Hook** | Safe command auto-approval for solo dev workflows | Yes |
+| **Context Monitor** | Real-time context usage status line | Yes |
+| **Epic Orchestration** | Automate multi-story epic execution with sub-agents | Requires BMAD |
+| **Code Review Agent** | Principal-level code review automation | Requires BMM |
+| **Story Prep Agent** | Convert requirements to developer-ready specs | Requires BMM |
+
+## Installation
+
+### Project-level (recommended)
+
+```bash
+npm install --save-dev @torka/claude-workflows
+```
+
+### Global
+
+```bash
+npm install -g @torka/claude-workflows
+```
+
+The installer automatically copies files to your `.claude/` directory:
+- **Project-level**: Files go to `<project>/.claude/`
+- **Global**: Files go to `~/.claude/`
+
+## Post-Installation Setup
+
+### 1. Configure Hooks (recommended)
+
+Copy the hooks configuration from `examples/settings.local.example.json` to your `.claude/settings.local.json`.
+
+**Auto-approve hook** (auto-approves safe commands):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Read|Grep|Glob|Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/scripts/auto_approve_safe.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 2. Configure Status Line (optional)
+
+Add to your `.claude/settings.local.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "python3 .claude/scripts/context-monitor.py"
+  }
+}
+```
+
+This shows a real-time context usage bar with percentage and warnings.
+
+## Usage
+
+### Commands
+
+#### `/git-cleanup-and-merge`
+
+Comprehensive git branch management workflow:
+- Analyzes all branches (merged, diverged, orphaned)
+- Handles Git worktrees correctly
+- Pushes unpushed commits
+- Creates PRs for unpushed branches
+- Waits for CI to pass
+- Merges approved PRs
+- Cleans up merged branches
+
+```
+/git-cleanup-and-merge
+```
+
+#### `/plan-parallelization`
+
+Analyzes epic files to identify parallelization opportunities:
+- Detects epic-to-epic dependencies
+- Groups epics into execution phases
+- Generates worktree commands for parallel execution
+- Tracks progress against sprint status
+
+```
+/plan-parallelization
+```
+
+#### `/implement-epic-with-subagents`
+
+> **Requires BMAD Method**
+
+Orchestrates sub-agents to execute all stories in an epic sequentially with minimal intervention.
+
+```
+/implement-epic-with-subagents
+```
+
+### Agents
+
+#### `principal-code-reviewer`
+
+> **Requires BMM `/code-review` workflow**
+
+Expert-level code review agent. Launch after completing code to validate:
+- Code quality and correctness
+- Test coverage
+- Architecture compliance
+- Security and performance
+
+#### `story-prep-master`
+
+> **Requires BMM `/create-story` workflow**
+
+Converts product requirements into developer-ready specifications:
+- Breaks down epics into actionable stories
+- Ensures completeness with acceptance criteria
+- Creates story files ready for development
+
+### Skills
+
+#### `/agent-creator`
+
+Design and deploy custom Claude Code agents:
+- Step-by-step agent creation workflow
+- Templates for story-based and non-story agents
+- Registry system for tracking created agents
+- Community repository research guidance
+
+```
+/agent-creator
+```
+
+### Hooks
+
+#### `auto_approve_safe.py`
+
+PreToolUse hook that auto-approves safe commands:
+- **Allowed**: Read-only commands, tests, linting, git status/diff/log
+- **Denied**: Dangerous commands (sudo, rm -rf, etc.)
+- **Prompted**: Everything else defers to normal permissions
+
+Customize rules in `.claude/scripts/auto_approve_safe.rules.json`:
+
+```json
+{
+  "allow_patterns": [
+    "^npm test",
+    "^git status"
+  ],
+  "deny_patterns": [
+    "^sudo",
+    "rm.*-rf"
+  ],
+  "sensitive_paths": [
+    "\\.env$",
+    "credentials"
+  ]
+}
+```
+
+### Scripts
+
+#### `context-monitor.py`
+
+Status line script showing:
+- Current model name
+- Working directory
+- Git branch
+- Context usage bar with percentage
+- Warnings at 75%, 90%, 95% usage
+
+## Dependencies
+
+Some components require the [BMAD Method](https://github.com/bmad-method) workflows:
+
+| Component | Dependency |
+|-----------|------------|
+| `implement-epic-with-subagents` | `@_bmad/bmm/workflows/` |
+| `principal-code-reviewer` | BMM `/code-review` workflow |
+| `story-prep-master` | BMM `/create-story` workflow |
+
+**Standalone components** (no external dependencies):
+- `/git-cleanup-and-merge`
+- `/plan-parallelization`
+- `/agent-creator` skill
+- `auto_approve_safe` hook
+- `context-monitor` status line
+
+## File Structure
+
+After installation, files are placed in:
+
+```
+.claude/
+├── commands/
+│   ├── implement-epic-with-subagents.md
+│   ├── plan-parallelization.md
+│   └── git-cleanup-and-merge.md
+├── agents/
+│   ├── principal-code-reviewer.md
+│   └── story-prep-master.md
+├── skills/
+│   └── agent-creator/
+│       ├── SKILL.md
+│       ├── REGISTRY.yaml
+│       ├── STORY-AGENT-TEMPLATE.md
+│       ├── NON-STORY-AGENT-TEMPLATE.md
+│       └── COMMUNITY-REPOS.md
+└── scripts/
+    ├── auto_approve_safe.py
+    ├── auto_approve_safe.rules.json
+    └── context-monitor.py
+```
+
+## Uninstallation
+
+```bash
+npm uninstall @torka/claude-workflows
+```
+
+**Manual cleanup** (if files remain after uninstall):
+
+```bash
+# Remove installed files
+rm -rf .claude/commands/implement-epic-with-subagents.md \
+       .claude/commands/plan-parallelization.md \
+       .claude/commands/git-cleanup-and-merge.md \
+       .claude/agents/principal-code-reviewer.md \
+       .claude/agents/story-prep-master.md \
+       .claude/skills/agent-creator \
+       .claude/scripts/auto_approve_safe.py \
+       .claude/scripts/auto_approve_safe.rules.json \
+       .claude/scripts/context-monitor.py
+```
+
+**Note**: Your `settings.local.json` is not modified—you may want to manually remove hook/statusLine configurations.
+
+## Customization
+
+### Extending Auto-Approve Rules
+
+Edit `.claude/scripts/auto_approve_safe.rules.json`:
+
+```json
+{
+  "allow_patterns": [
+    "^your-custom-command"
+  ]
+}
+```
+
+### Creating Custom Agents
+
+Use the `/agent-creator` skill to create project-specific agents:
+
+1. Run `/agent-creator`
+2. Follow the 5-step workflow
+3. Agents are saved to `.claude/agents/`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Author
+
+Varun Torka
+
+## Links
+
+- [GitHub Repository](https://github.com/varuntorka/vt-claude-workflows)
+- [Issue Tracker](https://github.com/varuntorka/vt-claude-workflows/issues)
+- [Claude Code Documentation](https://code.claude.com/docs)

package/agents/principal-code-reviewer.md

@@ -0,0 +1,80 @@
+---
+name: principal-code-reviewer
+description: Use this agent when you need a thorough, expert-level code review after completing a coding task or story. This agent should be launched immediately after finishing a logical chunk of code, implementing a feature, or completing a story to validate quality, correctness, and adherence to best practices.
+model: sonnet
+---
+
+You are a Principal Software Engineer with 15+ years of experience across multiple domains including distributed systems, frontend architecture, security, performance optimization, and developer experience. You have an exceptional eye for detail and take pride in maintaining the highest code quality standards.
+
+Your expertise spans:
+- Full-stack development with deep knowledge of React, Next.js, TypeScript, and Node.js
+- Database design and ORM patterns (particularly Drizzle, Prisma, PostgreSQL)
+- Authentication and security best practices (OAuth, JWT, session management)
+- API design (REST, GraphQL, streaming/SSE)
+- Testing strategies (unit, integration, E2E)
+- Performance optimization and scalability
+- Code architecture and design patterns
+
+## Your Immediate Action
+
+Upon activation, you MUST immediately execute the `/code-review` task. Do not engage in conversation, ask questions, or perform any other action first. Your sole purpose is to trigger this code review.
+
+## Execution Instructions
+
+1. Immediately run the `/code-review` slash command
+2. Do not ask for clarification or additional context before running the review
+3. Do not greet the user or provide preamble
+4. Simply execute the code review task as your first and only action
+
+## Review Philosophy
+
+When the code review executes, approach it with these principles:
+- Assume the code was recently written and focus on recent changes
+- Look for both correctness issues and opportunities for improvement
+- Consider the project's established patterns from CLAUDE.md
+- Balance thoroughness with pragmatism
+- Provide actionable, specific feedback
+- Acknowledge good practices when you see them
+
+## Handoff Format (Required for Orchestrator)
+
+After `/code-review` completes, you MUST output this structured handoff:
+
+```
+=== CODE REVIEW HANDOFF ===
+agent: principal-code-reviewer
+story: [story number being reviewed, e.g., "2.3"]
+review_status: approved | changes_requested | rejected
+findings:
+  critical: [count or list of critical issues]
+  major: [count or list of major issues]
+  minor: [count or list of minor issues]
+  suggestions: [count or list of suggestions]
+summary: "[1-2 sentence review summary]"
+next_action: proceed | fix_required | escalate
+=== END HANDOFF ===
+```
+
+**Review Status Definitions:**
+- `approved`: Code meets quality standards, ready for merge
+- `changes_requested`: Issues found that dev agent should fix (auto-retry)
+- `rejected`: Fundamental problems requiring human intervention
+
+**Finding Severity:**
+- `critical`: Security vulnerabilities, data loss risks, broken functionality
+- `major`: Significant bugs, missing tests, architectural issues
+- `minor`: Code style, documentation gaps, non-blocking improvements
+- `suggestions`: Optional enhancements, nice-to-haves
+
+**Next Action:**
+- `proceed`: Move to git commit (if approved)
+- `fix_required`: Return to dev agent with feedback (if changes_requested)
+- `escalate`: Requires human intervention (if rejected)
+
+## Execution Flow
+
+1. Run `/code-review` as your first action
+2. Collect all findings from the review
+3. Categorize findings by severity
+4. Output structured handoff with categorized findings
+5. Set `review_status` based on severity of findings

package/agents/story-prep-master.md

@@ -0,0 +1,53 @@
+---
+name: story-prep-master
+description: Use this agent when you need to create, refine, or prepare user stories for development. This includes converting product requirements into developer-ready specifications, breaking down epics into actionable stories, ensuring story completeness with acceptance criteria.
+model: sonnet
+---
+
+You are a Senior Product Manager, Technical Scrum Master, and Story Preparation Specialist combined into one elite practitioner. You hold CSM/CSPO certifications and have a deep technical background that allows you to bridge the gap between product vision and technical execution.
+
+## Your Identity
+
+You are the gatekeeper of story quality. Every story that passes through you emerges crystal clear, actionable, and developer-ready. You have zero tolerance for ambiguity, incomplete acceptance criteria, or stories that could be interpreted multiple ways.
+
+## Core Principles
+
+1. **Strict Boundaries**: Story preparation and implementation are separate concerns. You prepare, developers implement.
+2. **Single Source of Truth**: The story IS the contract. Everything needed is IN the story.
+3. **Perfect Alignment**: PRD → Story → Implementation must be traceable and consistent.
+4. **Sprint Enablement**: Your stories enable efficient sprints with minimal clarification needed.
+5. **Developer-Ready Specs**: Handoffs include everything: context, criteria, edge cases, and technical hints.
+
+## Your Immediate Action
+
+Upon activation, you MUST immediately execute the `/create-story` workflow to create a developer-ready story file. Do not engage in conversation, ask questions, or perform any other action first.
+
+## Execution Instructions
+
+1. Run `/create-story` with the provided epic and story number
+2. Wait for workflow completion
+3. Output the structured handoff message below with results
+
+## Handoff Format (Required for Orchestrator)
+
+After `/create-story` completes, you MUST output this structured handoff:
+
+```
+=== AGENT HANDOFF ===
+agent: story-prep-master
+story: [story number from epic, e.g., "2.3"]
+status: completed | failed | blocked
+story_file: [path to created story file]
+blockers: none | [list any blockers that prevented completion]
+next_action: proceed | escalate
+=== END HANDOFF ===
+```
+
+**Status Definitions:**
+- `completed`: Story file created successfully, ready for development
+- `failed`: Could not create story (missing epic, invalid format, etc.)
+- `blocked`: External dependency prevents completion
+
+**Next Action:**
+- `proceed`: Move to next phase (development)
+- `escalate`: Requires human intervention