@pjmendonca/devflow 1.10.0 → 1.10.2

package/.claude/commands/adversarial.md

@@ -0,0 +1,10 @@
+---
+description: Run adversarial (critical) code review with Opus
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+Run the Devflow adversarial review for story: $ARGUMENTS
+
+Execute: `devflow adversarial $ARGUMENTS`
+
+This performs a critical, thorough review using the Opus model.

package/.claude/commands/agent.md

@@ -0,0 +1,10 @@
+---
+description: Invoke a specific Devflow agent
+argument-hint: <agent-name>
+---
+
+Invoke the Devflow agent: $ARGUMENTS
+
+Execute: `devflow agent $ARGUMENTS`
+
+Available agents: architect, ba, dev, maintainer, pm, reviewer, sm

package/.claude/commands/bugfix.md

@@ -0,0 +1,8 @@
+---
+description: Fix a bug
+argument-hint: <bug-id>
+---
+
+Run the Devflow bugfix automation for: $ARGUMENTS
+
+Execute: `devflow bugfix $ARGUMENTS`

package/.claude/commands/checkpoint.md

@@ -0,0 +1,30 @@
+---
+description: Create or restore context checkpoints
+argument-hint: [save|restore|list] [checkpoint-name]
+---
+
+Manage Devflow context checkpoints: $ARGUMENTS
+
+Execute: `devflow checkpoint $ARGUMENTS`
+
+This manages context preservation checkpoints:
+- Save current context state before risky operations
+- Restore previous context if work is lost
+- List available checkpoints for a story
+
+Commands:
+- `save <name>` - Save current context as checkpoint
+- `restore <name>` - Restore from checkpoint
+- `list` - List available checkpoints
+- `auto` - Enable automatic checkpointing
+
+Examples:
+- `/checkpoint save before-refactor` - Save checkpoint
+- `/checkpoint list` - Show available checkpoints
+- `/checkpoint restore before-refactor` - Restore state
+
+Automatic checkpointing occurs at:
+- Before each agent phase starts
+- When approaching context limits
+- After major milestones
+

package/.claude/commands/collab.md

@@ -0,0 +1,30 @@
+---
+description: Run collaborative story with mode selection
+argument-hint: <story-key> [--swarm|--pair|--auto]
+---
+
+Run Devflow collaboration for: $ARGUMENTS
+
+Execute: `devflow collab $ARGUMENTS`
+
+This is the unified collaboration CLI with all modes:
+
+Modes:
+- `--auto` - Auto-route to best agents (default)
+- `--swarm` - Multi-agent debate/consensus
+- `--pair` - DEV + REVIEWER pair programming
+- `--sequential` - Traditional sequential pipeline
+
+Options:
+- `--agents AGENT1,AGENT2` - Specify agents (for swarm)
+- `--max-iterations N` - Max iterations (default: 3)
+- `--budget N` - Budget limit in USD
+- `--memory` - Show shared memory
+- `--query "Q"` - Query knowledge graph
+- `--route-only` - Preview routing only
+
+Examples:
+- `/collab 3-5 --swarm` - Run swarm mode
+- `/collab 3-5 --pair` - Run pair programming
+- `/collab "fix auth bug" --auto` - Auto-route task
+

package/.claude/commands/costs.md

@@ -0,0 +1,27 @@
+---
+description: View cost dashboard and spending analytics
+argument-hint: [--period day|week|month]
+---
+
+View Devflow cost dashboard: $ARGUMENTS
+
+Execute: `devflow costs $ARGUMENTS`
+
+This displays cost tracking and analytics:
+- Total spend by model (Opus, Sonnet, Haiku)
+- Cost breakdown by agent
+- Cost breakdown by story/task
+- Budget utilization tracking
+- Cost trends over time
+
+Options:
+- `--period day` - Show today's costs
+- `--period week` - Show this week's costs
+- `--period month` - Show this month's costs
+- `--export csv` - Export to CSV file
+
+Examples:
+- `/costs` - Show current cost dashboard
+- `/costs --period week` - Show weekly breakdown
+- `/costs --by-agent` - Group costs by agent
+

package/.claude/commands/develop.md

@@ -0,0 +1,8 @@
+---
+description: Run development phase for a story
+argument-hint: <story-key>
+---
+
+Run the Devflow development phase for story: $ARGUMENTS
+
+Execute: `devflow develop $ARGUMENTS`

package/.claude/commands/devflow.md

@@ -0,0 +1,6 @@
+---
+description: Run any Devflow command
+argument-hint: <command> [args]
+---
+
+Run: `devflow $ARGUMENTS`

package/.claude/commands/handoff.md

@@ -0,0 +1,26 @@
+---
+description: View handoff summaries between agents
+argument-hint: <story-key> [--from AGENT] [--to AGENT]
+---
+
+View agent handoff summaries: $ARGUMENTS
+
+Execute: `devflow handoff $ARGUMENTS`
+
+This shows structured handoff information between agents:
+- What was completed in the previous phase
+- Decisions made and their rationale
+- Blockers or warnings for the next agent
+- Files modified with change summaries
+
+Options:
+- `--from AGENT` - Filter by source agent
+- `--to AGENT` - Filter by destination agent
+- `--latest` - Show only most recent handoff
+- `--export` - Export handoffs to markdown
+
+Examples:
+- `/handoff 3-5` - Show all handoffs for story
+- `/handoff 3-5 --from DEV --to REVIEWER` - Specific handoff
+- `/handoff 3-5 --latest` - Most recent handoff
+

package/.claude/commands/memory.md

@@ -0,0 +1,23 @@
+---
+description: View or query shared agent memory
+argument-hint: <story-key> [--query "question"]
+---
+
+View shared memory for: $ARGUMENTS
+
+Execute: `devflow memory $ARGUMENTS`
+
+This displays the shared memory and knowledge graph for a story:
+- Cross-agent shared memory pool
+- Decision tracking with knowledge graph
+- Learnings and context from all agents
+
+Query Mode:
+Use `--query` to ask questions about past decisions:
+- `/memory 3-5 --query "What did ARCHITECT decide about auth?"`
+- `/memory 3-5 --query "Why was the database schema changed?"`
+
+Examples:
+- `/memory 3-5` - Show all shared memory for story 3-5
+- `/memory 3-5 --query "security decisions"` - Query specific topic
+

package/.claude/commands/pair.md

@@ -0,0 +1,24 @@
+---
+description: Run pair programming mode (DEV + REVIEWER interleaved)
+argument-hint: <story-key>
+---
+
+Run Devflow pair programming for: $ARGUMENTS
+
+Execute: `devflow pair $ARGUMENTS`
+
+This runs DEV and REVIEWER in an interleaved pair programming mode:
+- DEV implements code in small, reviewable chunks
+- REVIEWER provides immediate feedback after each chunk
+- DEV addresses issues before continuing to next chunk
+- Results in higher quality code with fewer late-stage revisions
+
+Benefits:
+- Real-time feedback loops during implementation
+- Issues caught early, not at final review
+- Better knowledge sharing between agents
+- Higher approval rates
+
+Example:
+- `/pair 3-5` - Run pair programming for story 3-5
+

package/.claude/commands/personalize.md

@@ -0,0 +1,15 @@
+---
+description: Personalize agent behavior with guided wizard
+argument-hint: [agent-name]
+---
+
+Run the agent personalization wizard to customize agent behavior.
+
+Execute: `python3 tooling/scripts/personalize_agent.py $ARGUMENTS`
+
+Available agents: dev, sm, ba, architect, pm, writer, maintainer, reviewer
+
+Examples:
+- `/personalize dev` - Customize the developer agent
+- `/personalize` - Interactive agent selection
+- `/personalize --list` - Show available templates

package/.claude/commands/review.md

@@ -0,0 +1,8 @@
+---
+description: Run code review for a story
+argument-hint: <story-key>
+---
+
+Run the Devflow code review for story: $ARGUMENTS
+
+Execute: `devflow review $ARGUMENTS`

package/.claude/commands/route.md

@@ -0,0 +1,26 @@
+---
+description: Auto-route task to best agents
+argument-hint: <task-description>
+---
+
+Auto-route task to optimal agents: $ARGUMENTS
+
+Execute: `devflow route $ARGUMENTS`
+
+This intelligently selects the best agents based on task analysis:
+- Analyzes task description for keywords and patterns
+- Detects task type (bugfix, security, feature, refactor, etc.)
+- Estimates complexity (trivial to critical)
+- Routes to appropriate specialists
+
+Task type detection examples:
+- "fix login bug" -> MAINTAINER, DEV, REVIEWER
+- "security vulnerability" -> SECURITY, ARCHITECT, REVIEWER
+- "new user profile feature" -> BA, ARCHITECT, DEV, REVIEWER
+- "refactor auth module" -> ARCHITECT, DEV, MAINTAINER
+
+Examples:
+- `/route fix authentication timeout` - Routes to bug specialists
+- `/route add payment integration` - Routes to feature team
+- `/route --route-only fix memory leak` - Preview routing only
+

package/.claude/commands/story.md

@@ -0,0 +1,10 @@
+---
+description: Run full story pipeline (context + dev + review)
+argument-hint: <story-key>
+---
+
+Run the Devflow story automation for story: $ARGUMENTS
+
+Execute: `devflow story $ARGUMENTS`
+
+This runs the full pipeline: context creation, development, and review.

package/.claude/commands/swarm.md

@@ -0,0 +1,22 @@
+---
+description: Run multi-agent swarm mode (debate/consensus)
+argument-hint: <story-key> [--agents AGENT1,AGENT2,...]
+---
+
+Run Devflow swarm mode for: $ARGUMENTS
+
+Execute: `devflow swarm $ARGUMENTS`
+
+This runs multi-agent collaboration where agents debate and iterate until consensus:
+- Multiple agents analyze the task simultaneously
+- Agents provide feedback on each other's work
+- Issues are addressed through iterative refinement
+- Continues until consensus or max iterations reached
+
+Default agents: ARCHITECT, DEV, REVIEWER
+
+Examples:
+- `/swarm 3-5` - Run swarm with default agents
+- `/swarm 3-5 --agents ARCHITECT,DEV,REVIEWER,SECURITY` - Custom agents
+- `/swarm 3-5 --max-iter 5` - Increase max iterations
+

package/.claude/skills/github-cli/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: github-cli
+description: Execute GitHub CLI (gh) commands to manage repositories, pull requests, issues, workflows, and more. Use when working with GitHub operations like creating PRs, listing issues, managing branches, checking workflow runs, or any gh command automation.
+---
+
+# GitHub CLI Automation
+
+Use the GitHub CLI (gh) to automate GitHub repository operations efficiently.
+
+## Prerequisites
+
+- GitHub CLI must be installed: `gh --version`
+- Authentication required: `gh auth status`
+
+## Core Operations
+
+### Repository Management
+
+```bash
+# View repository information
+gh repo view
+
+# Clone a repository
+gh repo clone owner/repo
+
+# Fork a repository
+gh repo fork
+
+# Create a new repository
+gh repo create my-new-repo --public
+```
+
+### Pull Requests
+
+```bash
+# Create a pull request
+gh pr create --title "Feature: Add new functionality" --body "Description"
+
+# List pull requests
+gh pr list --state open
+gh pr list --author @me
+
+# View PR details
+gh pr view 123
+
+# Check out a PR locally
+gh pr checkout 123
+
+# Merge a pull request
+gh pr merge 123 --squash
+
+# Review PR status
+gh pr status
+```
+
+### Issues
+
+```bash
+# Create an issue
+gh issue create --title "Bug: Something broke" --body "Description"
+
+# List issues
+gh issue list --state open
+gh issue list --label bug --assignee @me
+
+# View issue details
+gh issue view 456
+
+# Close an issue
+gh issue close 456
+
+# Reopen an issue
+gh issue reopen 456
+```
+
+### Workflow Runs
+
+```bash
+# List workflow runs
+gh run list --limit 10
+
+# View specific run
+gh run view 12345
+
+# Watch a running workflow
+gh run watch
+
+# Rerun a failed workflow
+gh run rerun 12345
+
+# List workflow run logs
+gh run view 12345 --log
+```
+
+### Branches
+
+```bash
+# List branches (via API)
+gh api repos/:owner/:repo/branches
+
+# Delete remote branch
+gh api -X DELETE repos/:owner/:repo/git/refs/heads/branch-name
+```
+
+### Releases
+
+```bash
+# Create a release
+gh release create v1.0.0 --title "Release 1.0.0" --notes "Release notes"
+
+# List releases
+gh release list
+
+# Download release assets
+gh release download v1.0.0
+```
+
+### Gists
+
+```bash
+# Create a gist
+gh gist create file.txt --public
+
+# List your gists
+gh gist list
+
+# View a gist
+gh gist view <gist-id>
+```
+
+## Advanced Usage
+
+### JSON Output for Parsing
+
+Many commands support `--json` for structured output:
+
+```bash
+# Get PR data as JSON
+gh pr list --json number,title,state,headRefName
+
+# Get issue data as JSON
+gh issue list --json number,title,labels,state
+
+# Parse with jq
+gh pr list --json number,title | jq '.[] | select(.title | contains("bug"))'
+```
+
+### API Access
+
+Direct API access for advanced operations:
+
+```bash
+# Generic API call
+gh api repos/:owner/:repo/branches
+
+# With pagination
+gh api repos/:owner/:repo/pulls --paginate
+
+# POST request
+gh api repos/:owner/:repo/issues -f title="New Issue" -f body="Description"
+```
+
+### Checking for Stale Branches
+
+```bash
+# List merged branches
+git branch -r --merged main | grep -v 'main\|HEAD'
+
+# Get PR information
+gh pr list --state merged --json headRefName,mergedAt
+```
+
+## Best Practices
+
+1. **Always check auth status first**: Run `gh auth status` before operations
+2. **Use structured output**: Prefer `--json` when parsing results programmatically
+3. **Check command success**: Verify exit codes and output before proceeding
+4. **Use help**: Run `gh <command> --help` for detailed syntax
+5. **Batch operations**: Combine commands with shell scripting for bulk operations
+
+## Common Workflows
+
+### Creating and Merging a PR
+
+```bash
+# Push your changes
+git push origin feature-branch
+
+# Create PR
+gh pr create --title "Feature: Description" --body "Detailed description"
+
+# Wait for CI/checks
+gh pr checks
+
+# Merge when ready
+gh pr merge --squash
+```
+
+### Cleaning Up Merged Branches
+
+```bash
+# List merged PRs
+gh pr list --state merged --json headRefName --limit 20
+
+# Delete remote branches (carefully!)
+# gh api -X DELETE repos/:owner/:repo/git/refs/heads/branch-name
+```
+
+### Release Management
+
+```bash
+# Tag and create release
+git tag v1.0.0
+git push --tags
+gh release create v1.0.0 --generate-notes
+
+# Or with custom notes
+gh release create v1.0.0 --title "Version 1.0.0" --notes "Release notes here"
+```
+
+## Error Handling
+
+```bash
+# Check if gh is installed
+if ! command -v gh &> /dev/null; then
+    echo "GitHub CLI not installed"
+    exit 1
+fi
+
+# Check authentication
+if ! gh auth status &> /dev/null; then
+    echo "Not authenticated. Run: gh auth login"
+    exit 1
+fi
+```
+
+## Reference
+
+- Official docs: https://cli.github.com/manual/
+- All commands: `gh help`
+- Command-specific help: `gh <command> --help`

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.10.2] - 2025-12-24
+
+### Fixed
+- **npx Command** - Fixed "could not determine executable to run" error when running `npx @pjmendonca/devflow`
+  - Added main `devflow` bin entry to package.json
+  - Created bin/devflow.js as smart entry point with context detection
+  - Outside Devflow project: automatically scaffolds new project
+  - Inside Devflow project: shows help and dispatches to commands
+  - Simplified workflow: single command for both setup and usage
+
+## [1.10.1] - 2025-12-24
+
+### Fixed
+- **Claude Code Skills Distribution** - Include .claude directory in npm package and installation
+  - Added .claude/ to package.json files array for npm distribution
+  - Added .claude/ to create-devflow.js itemsToCopy for project initialization
+  - Ensures 16 custom commands and 1 skill are immediately available after installation
+  - Commands include: story, devflow, adversarial, agent, bugfix, checkpoint, collab, costs, develop, handoff, memory, pair, personalize, review, route, swarm
+  - Skills include: github-cli for GitHub operations
+
 ## [1.10.0] - 2025-12-23
 
 ### Added

package/README.md

@@ -44,7 +44,7 @@ A production-ready, portable workflow automation system that uses Claude Code CL
 
 ### Installation
 
-**Option 1: Quick Start (Recommended - Creates Devflow folder)**
+**Option 1: Quick Start**
 
 This creates a new "Devflow" directory with all necessary files:
 
@@ -77,90 +77,6 @@ npx devflow-validate
 npx devflow-init
 ```
 
-See [NPM Installation Guide](docs/NPM_INSTALLATION.md) for detailed instructions and troubleshooting.
-
-**Option 3: pip (Python Ecosystem)**
-
-```bash
-# Clone the repository
-git clone https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow.git
-cd Devflow
-
-# Install via pip
-pip install .
-
-# Verify installation
-devflow-validate
-```
-
-**Option 4: Manual Installation (macOS/Linux)**
-
-Clone and Setup:
-
-```bash
-# Clone this repository
-git clone https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow.git
-cd Devflow
-
-# Copy to your project
-cp -r tooling /path/to/your/project/
-
-# Run setup wizard
-cd /path/to/your/project/tooling/scripts
-./init-project-workflow.sh
-```
-
-Direct Copy:
-
-```bash
-# Download latest release
-curl -L https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow/archive/main.tar.gz | tar xz
-
-# Move to your project
-mv Devflow-main/tooling /path/to/your/project/
-
-# Manual config
-cd /path/to/your/project/tooling/.automation
-cp config.sh.template config.sh
-vim config.sh
-```
-
-**Option 5: Manual Installation (Windows)**
-
-Clone and Setup (Recommended):
-
-```powershell
-# Clone this repository
-git clone https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow.git
-cd Devflow
-
-# Copy to your project
-Copy-Item -Recurse tooling C:\path\to\your\project\
-
-# Set execution policy (first time only, run as Admin)
-Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
-
-# Run setup wizard
-cd C:\path\to\your\project\tooling\scripts
-.\init-project-workflow.ps1
-```
-
-Direct Copy:
-
-```powershell
-# Download latest release
-Invoke-WebRequest -Uri "https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow/archive/main.zip" -OutFile main.zip
-Expand-Archive main.zip -DestinationPath .
-
-# Move to your project
-Move-Item Devflow-main\tooling C:\path\to\your\project\
-
-# Manual config
-cd C:\path\to\your\project\tooling\.automation
-Copy-Item config.ps1.template config.ps1
-notepad config.ps1
-```
-
 ### Agent Personas
 
 | Agent | Model | Cost | Use Case |
@@ -616,7 +532,7 @@ Free to use in commercial and personal projects.
 
 
 <!-- VERSION_START - Auto-updated by update_version.py -->
-**Version**: 1.10.0
+**Version**: 1.10.2
 **Status**: Production Ready
-**Last Updated**: 2025-12-23
+**Last Updated**: 2025-12-24
 <!-- VERSION_END -->

package/bin/create-devflow.js

@@ -67,6 +67,7 @@ const itemsToCopy = [
   { type: 'dir', name: 'tooling' },
   { type: 'dir', name: 'bin' },
   { type: 'dir', name: 'lib' },
+  { type: 'dir', name: '.claude' },
   { type: 'file', name: 'LICENSE' },
   { type: 'file', name: 'README.md' },
   { type: 'file', name: 'CHANGELOG.md' },

package/bin/devflow.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const commands = {
+  'init': 'Initialize Devflow in your project',
+  'story': 'Run full story pipeline (context + dev + review)',
+  'collab': 'Run collaborative story with mode selection',
+  'checkpoint': 'Create or restore context checkpoints',
+  'memory': 'View or query shared agent memory',
+  'cost': 'View cost dashboard and spending analytics',
+  'validate': 'Validate project configuration',
+  'create-persona': 'Create a new agent persona',
+  'personalize': 'Personalize agent behavior with guided wizard',
+  'validate-overrides': 'Validate override configurations',
+  'new-doc': 'Create new documentation',
+  'tech-debt': 'Analyze and track technical debt',
+  'setup-checkpoint': 'Setup checkpoint system',
+  'version': 'Show version information'
+};
+
+/**
+ * Check if we're in a Devflow project
+ */
+function isInDevflowProject() {
+  const indicators = [
+    'tooling/.automation',
+    'tooling/scripts',
+    '.claude'
+  ];
+
+  return indicators.some(indicator => fs.existsSync(path.join(process.cwd(), indicator)));
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  console.log('Devflow - Development workflow automation with Claude Code\n');
+  console.log('Usage: devflow <command> [options]\n');
+  console.log('Available commands:\n');
+
+  Object.entries(commands).forEach(([cmd, desc]) => {
+    console.log(`  ${cmd.padEnd(20)} ${desc}`);
+  });
+
+  console.log('\nRun "devflow <command> --help" for more information on a command.');
+  console.log('\nGet started: devflow init');
+}
+
+const args = process.argv.slice(2);
+
+// If no arguments or --help, check if we're in a project
+if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (!isInDevflowProject()) {
+    // Not in a project - run scaffolder
+    console.log('No Devflow project detected. Running project scaffolder...\n');
+    const createScript = require.resolve('./create-devflow.js');
+    const child = spawn('node', [createScript], { stdio: 'inherit' });
+    child.on('exit', (code) => process.exit(code || 0));
+  } else {
+    // In a project - show help
+    showHelp();
+    process.exit(0);
+  }
+} else {
+  // Command provided
+  const command = args[0];
+
+  if (commands[command]) {
+    const binPath = require.resolve(`./devflow-${command}.js`);
+    const child = spawn('node', [binPath, ...args.slice(1)], { stdio: 'inherit' });
+    child.on('exit', (code) => process.exit(code || 0));
+  } else {
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "devflow --help" to see available commands.');
+    process.exit(1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pjmendonca/devflow",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Development workflow automation with Claude Code - agent-based development system with cost tracking",
   "keywords": [
     "devflow",
@@ -24,6 +24,7 @@
     "name": "Pedro Jose da Rocha Mendonca"
   },
   "bin": {
+    "devflow": "bin/devflow.js",
     "create-devflow": "bin/create-devflow.js",
     "devflow-cost": "bin/devflow-cost.js",
     "devflow-validate": "bin/devflow-validate.js",
@@ -44,6 +45,7 @@
     "bin/",
     "lib/",
     "tooling/",
+    ".claude/",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/tooling/scripts/lib/__init__.py

@@ -18,7 +18,7 @@ Usage:
     from lib.agent_router import AgentRouter
 """
 
-__version__ = "1.10.0"
+__version__ = "1.10.2"
 
 # Lazy imports to avoid circular dependencies
 __all__ = [