@pjmendonca/devflow 1.9.0 → 1.10.1

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code](https://img.shields.io/badge/Claude-Code-5A67D8)](https://claude.com/claude-code)
 
-## 🚀 What is This?
+## What is This?
 
 A production-ready, portable workflow automation system that uses Claude Code CLI to implement user stories with minimal human intervention. Think "CI/CD for development" - but instead of deploying code, it writes code.
 
@@ -14,7 +14,7 @@ A production-ready, portable workflow automation system that uses Claude Code CL
 - **Multi-Persona Agent System** - 8 specialized AI agents (SM, DEV, BA, ARCHITECT, PM, WRITER, MAINTAINER, REVIEWER)
 - **Smart Model Usage** - Opus for development, Sonnet for planning (40-60% cost savings)
 - **Context Preservation** - Automatic checkpoints prevent work loss from context limits
-- **Full Automation** - Context → Development → Testing → Review → Commit pipeline
+- **Full Automation** - Context -> Development -> Testing -> Review -> Commit pipeline
 - **Greenfield + Brownfield** - Supports both new features AND existing codebase maintenance
 - **Agent Personalization** - Agent overrides and persistent agent memory
 - **Claude Code Integration** - Native slash commands (`/story`, `/swarm`, `/pair`, `/route`, etc.)
@@ -26,7 +26,7 @@ A production-ready, portable workflow automation system that uses Claude Code CL
 - **Project Agnostic** - Works with Flutter, Node.js, Python, Rust, Go, Ruby, etc.
 - **Guided Setup** - Interactive wizard guides you through installation
 
-## 📦 Quick Start
+## Quick Start
 
 ### Prerequisites
 
@@ -44,119 +44,37 @@ A production-ready, portable workflow automation system that uses Claude Code CL
 
 ### Installation
 
-**Option 1: npm (Easiest - All Platforms)**
+**Option 1: Quick Start**
 
-```bash
-# Install globally via npm
-npm install -g @pjmendonca/devflow
-
-# Verify installation
-devflow-validate
-
-# Start using
-devflow-init
-```
-
-**Requirements:** Python 3.9+ and Node.js 14+
-
-See [NPM Installation Guide](docs/NPM_INSTALLATION.md) for detailed instructions and troubleshooting.
-
-**Option 2: 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 3: Manual Installation (macOS/Linux)**
-
-Clone and Setup (Recommended):
-
-```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:
+This creates a new "Devflow" directory with all necessary files:
 
 ```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
-```
+# Create a new Devflow project directory
+npx @pjmendonca/devflow@latest
 
-**Option 4: Manual Installation (Windows)**
+# This will:
+# 1. Create a "Devflow" folder in your current directory
+# 2. Copy all essential files into it
+# 3. Run the interactive setup wizard
 
-Clone and Setup (Recommended):
-
-```powershell
-# Clone this repository
-git clone https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow.git
+# Then use it:
 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
+/story <key>
 ```
 
-**Running Stories on Windows:**
+**Requirements:** Python 3.9+ and Node.js 14+
 
-```powershell
-# Full pipeline with live monitoring
-.\run-story.ps1 -StoryKey "3-5"
+**Option 2: Add to Existing Project**
 
-# Development only
-.\run-story.ps1 -StoryKey "3-5" -Develop
+Install Devflow into your current project:
 
-# With specific model
-.\run-story.ps1 -StoryKey "3-5" -Model opus
+```bash
+# Local installation
+npm install @pjmendonca/devflow
 
-# Disable auto-commit
-.\run-story.ps1 -StoryKey "3-5" -NoCommit
+# IMPORTANT: Local installs require npx to run commands
+npx devflow-validate
+npx devflow-init
 ```
 
 ### Agent Personas
@@ -172,7 +90,7 @@ notepad config.ps1
 | **MAINTAINER** | Opus/Sonnet | Varies | Bug fixes, refactoring, tech debt |
 | **REVIEWER** (Adversarial) | Opus | High | Critical code review, finds problems |
 
-## 💻 Claude Slash Commands
+## Claude Slash Commands
 
 Devflow provides native slash commands for Claude Code:
 
@@ -215,7 +133,7 @@ Devflow provides native slash commands for Claude Code:
 /memory 3-5 --query "auth decisions" # Query knowledge graph
 ```
 
-## 🧠 Knowledge Graph & Shared Memory
+## Knowledge Graph & Shared Memory
 
 Devflow features a sophisticated memory system that enables agents to share context, track decisions, and maintain institutional knowledge across the entire development workflow.
 
@@ -283,7 +201,7 @@ memory.add('DEV', 'Decided to use PostgreSQL for user data', tags=['database', '
 - `tags` - Searchable categorization tags
 - `references` - Links to related entries
 
-## 🤝 Agent Handoff System
+## Agent Handoff System
 
 The Agent Handoff System ensures seamless transitions between agents with structured context preservation. When one agent finishes their work, a comprehensive handoff summary is automatically generated for the next agent.
 
@@ -322,14 +240,14 @@ print(handoff)
 
 | From | To | Focus Areas |
 |------|-----|-------------|
-| SM → DEV | Acceptance criteria, technical context, patterns to follow |
-| SM → ARCHITECT | High-level requirements, system constraints, scale requirements |
-| ARCHITECT → DEV | Architecture decisions, design patterns, interface definitions |
-| DEV → REVIEWER | Implementation approach, key decisions, test coverage |
-| REVIEWER → DEV | Issues found, required changes, approval status |
-| BA → DEV | Refined requirements, acceptance criteria, edge cases |
+| SM -> DEV | Acceptance criteria, technical context, patterns to follow |
+| SM -> ARCHITECT | High-level requirements, system constraints, scale requirements |
+| ARCHITECT -> DEV | Architecture decisions, design patterns, interface definitions |
+| DEV -> REVIEWER | Implementation approach, key decisions, test coverage |
+| REVIEWER -> DEV | Issues found, required changes, approval status |
+| BA -> DEV | Refined requirements, acceptance criteria, edge cases |
 
-## 🐝 Multi-Agent Collaboration
+## Multi-Agent Collaboration
 
 Devflow supports advanced multi-agent collaboration modes for complex development tasks.
 
@@ -401,9 +319,9 @@ Let Devflow automatically select the best agents:
 **How it works:**
 - Analyzes task description for keywords
 - Considers file types and complexity
-- Routes to appropriate specialists (e.g., security → SECURITY agent)
+- Routes to appropriate specialists (e.g., security -> SECURITY agent)
 
-## 💰 Cost Tracking & Currency Configuration
+## Cost Tracking & Currency Configuration
 
 Devflow includes a comprehensive cost tracking system with multi-currency support and budget controls.
 
@@ -498,7 +416,7 @@ python tooling/scripts/cost_dashboard.py --summary
 - **Set budget limits** - Prevent runaway costs with phase-specific limits
 - **Monitor the dashboard** - Track spending patterns across stories
 
-## ⌨️ Shell Completion
+## Shell Completion
 
 Enable tab-completion for faster command entry.
 
@@ -561,7 +479,7 @@ devflow-help
 ./run-story.sh 3-5 --agents AR<TAB>  # Completes to ARCHITECT
 ```
 
-## � Security Considerations
+##  Security Considerations
 
 ### API Key Management
 
@@ -600,13 +518,13 @@ Devflow relies on the Claude Code CLI for API authentication. The CLI handles AP
 - No data is sent to external servers by Devflow (only to Anthropic's API via Claude CLI)
 - Context checkpoints may contain code snippets - review before sharing
 
-## �📜 License
+## License
 
 MIT License - see [LICENSE](LICENSE) for details.
 
 Free to use in commercial and personal projects.
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
 - Built for [Claude Code CLI](https://claude.com/claude-code)
 - Agent override system inspired by [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)
@@ -614,7 +532,7 @@ Free to use in commercial and personal projects.
 
 
 <!-- VERSION_START - Auto-updated by update_version.py -->
-**Version**: 1.9.0
+**Version**: 1.10.1
 **Status**: Production Ready
-**Last Updated**: 2025-12-22
+**Last Updated**: 2025-12-24
 <!-- VERSION_END -->

package/bin/create-devflow.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * create-devflow - NPM initializer for Devflow
+ *
+ * Creates a new "Devflow" directory with all necessary files
+ * Usage: npm create @pjmendonca/devflow
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Get the current working directory where the user ran the command
+const targetDir = path.join(process.cwd(), 'Devflow');
+
+// Get the source directory (where this package is installed)
+const sourceDir = path.join(__dirname, '..');
+
+console.log('\n========================================');
+console.log('  Devflow Project Initializer');
+console.log('========================================\n');
+
+// Check if Devflow directory already exists
+if (fs.existsSync(targetDir)) {
+  console.error(`Error: Directory "Devflow" already exists in ${process.cwd()}`);
+  console.error('Please remove it or run this command from a different location.\n');
+  process.exit(1);
+}
+
+console.log(`Creating Devflow directory at: ${targetDir}`);
+fs.mkdirSync(targetDir, { recursive: true });
+
+/**
+ * Recursively copy directory
+ */
+function copyDir(src, dest) {
+  // Create destination directory
+  fs.mkdirSync(dest, { recursive: true });
+
+  // Read source directory
+  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()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Copy file
+ */
+function copyFile(src, dest) {
+  const destDir = path.dirname(dest);
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+// Files and directories to copy
+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' },
+  { type: 'file', name: 'package.json' },
+  { type: 'file', name: '.gitignore' }
+];
+
+console.log('\nCopying project files...');
+for (const item of itemsToCopy) {
+  const src = path.join(sourceDir, item.name);
+  const dest = path.join(targetDir, item.name);
+
+  if (!fs.existsSync(src)) {
+    console.log(`  Skipping ${item.name} (not found)`);
+    continue;
+  }
+
+  try {
+    if (item.type === 'dir') {
+      console.log(`  Copying ${item.name}/ ...`);
+      copyDir(src, dest);
+    } else {
+      console.log(`  Copying ${item.name} ...`);
+      copyFile(src, dest);
+    }
+  } catch (error) {
+    console.error(`  Error copying ${item.name}: ${error.message}`);
+  }
+}
+
+console.log('\n[OK] Files copied successfully!\n');
+
+// Initialize git repo if not already in one
+console.log('Initializing git repository...');
+try {
+  process.chdir(targetDir);
+  execSync('git init', { stdio: 'ignore' });
+  console.log('[OK] Git repository initialized\n');
+} catch (error) {
+  console.log('[INFO] Git not available or already initialized\n');
+}
+
+// Run the setup wizard
+console.log('========================================');
+console.log('  Running Setup Wizard');
+console.log('========================================\n');
+
+try {
+  const initScript = path.join(targetDir, 'bin', 'devflow-init.js');
+
+  if (fs.existsSync(initScript)) {
+    console.log('Starting interactive setup wizard...\n');
+    execSync(`node "${initScript}"`, { stdio: 'inherit' });
+  } else {
+    console.log('[WARNING] Setup wizard not found. You may need to run it manually:');
+    console.log('  cd Devflow');
+    console.log('  npx devflow-init\n');
+  }
+} catch (error) {
+  console.log('[WARNING] Setup wizard encountered an issue.');
+  console.log('You can run it manually later with: npx devflow-init\n');
+}
+
+console.log('\n========================================');
+console.log('  Setup Complete!');
+console.log('========================================\n');
+console.log('Next steps:');
+console.log('  1. cd Devflow');
+console.log('  2. Review the README.md for usage instructions');
+console.log('  3. Start using Devflow with: /story <key>\n');
+console.log('Documentation: https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow\n');

package/lib/python-check.js

@@ -123,7 +123,7 @@ function checkPython() {
 
   if (!pythonCmd) {
     if (!silent) {
-      console.error(colorize('\n✗ Python not found', 'red'));
+      console.error(colorize('\n[X] Python not found', 'red'));
       console.error('\nDevflow requires Python 3.9 or higher.');
       console.error(getInstallInstructions());
       console.error(colorize('After installation, run:', 'yellow'));
@@ -147,7 +147,7 @@ function checkPython() {
 
   if (!currentVersion) {
     if (!silent) {
-      console.error(colorize('\n✗ Could not parse Python version', 'red'));
+      console.error(colorize('\n[X] Could not parse Python version', 'red'));
       console.error(`Version output: ${versionOutput}`);
       console.error('');
     }
@@ -157,7 +157,7 @@ function checkPython() {
   // Check if version is sufficient
   if (!isVersionSufficient(currentVersion, requiredVersion)) {
     if (!silent) {
-      console.error(colorize(`\n✗ Python ${currentVersion.join('.')} found, but ${REQUIRED_VERSION}+ required`, 'red'));
+      console.error(colorize(`\n[X] Python ${currentVersion.join('.')} found, but ${REQUIRED_VERSION}+ required`, 'red'));
       console.error(getInstallInstructions());
       console.error('');
     }
@@ -166,8 +166,8 @@ function checkPython() {
 
   // Success!
   if (!silent) {
-    console.log(colorize(`\n✓ Python ${currentVersion.join('.')} found (${pythonCmd})`, 'green'));
-    console.log(colorize('✓ Devflow is ready to use!\n', 'green'));
+    console.log(colorize(`\n[OK] Python ${currentVersion.join('.')} found (${pythonCmd})`, 'green'));
+    console.log(colorize('[OK] Devflow is ready to use!\n', 'green'));
     console.log(`Try: ${colorize('devflow-validate', 'blue')}\n`);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pjmendonca/devflow",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "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": {
+    "create-devflow": "bin/create-devflow.js",
     "devflow-cost": "bin/devflow-cost.js",
     "devflow-validate": "bin/devflow-validate.js",
     "devflow-story": "bin/devflow-story.js",
@@ -43,6 +44,7 @@
     "bin/",
     "lib/",
     "tooling/",
+    ".claude/",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/tooling/.automation/agents/dev.md

@@ -43,7 +43,7 @@ You are running in an automated pipeline with limited context window. To avoid l
 
 If you sense context is running low, output a warning:
 ```
-⚠️ CONTEXT WARNING: Approaching context limit. Prioritizing completion of current task.
+ CONTEXT WARNING: Approaching context limit. Prioritizing completion of current task.
 ```
 
 ## When Complete
@@ -66,7 +66,7 @@ After implementing all acceptance criteria and tests pass:
 
    Story: [story-key]
 
-   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   Generated with [Claude Code](https://claude.com/claude-code)
 
    Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
    ```

package/tooling/.automation/agents/reviewer.md

@@ -42,16 +42,16 @@ You are a critical code reviewer. Your job is to FIND PROBLEMS, not approve code
 Use these severity levels:
 
 ```
-🔴 CRITICAL - Must fix before merge
+CRITICAL - Must fix before merge
    Security vulnerabilities, data loss risks, crashes
 
-🟠 HIGH - Should fix before merge
+HIGH - Should fix before merge
    Logic errors, missing error handling, broken edge cases
 
-🟡 MEDIUM - Fix soon
+MEDIUM - Fix soon
    Code smells, missing tests, poor patterns
 
-🔵 LOW - Consider fixing
+LOW - Consider fixing
    Style issues, minor improvements, suggestions
 ```
 
@@ -62,15 +62,15 @@ For each issue found:
 ```
 [SEVERITY] Category: Brief Title
 
-📍 Location: path/to/file.dart:42
+Location: path/to/file.dart:42
 
-❌ Problem:
+ Problem:
 [What is wrong and why it matters]
 
-⚠️ Risk:
+ Risk:
 [What could go wrong if not fixed]
 
-✅ Suggested Fix:
+ Suggested Fix:
 [Specific code or approach to fix it]
 ```
 

package/tooling/.automation/agents/sm.md

@@ -57,5 +57,5 @@ You are running in an automated pipeline with limited context. To work efficient
 
 If you sense context is running low, output:
 ```
-⚠️ CONTEXT WARNING: Approaching limit. Saving current findings.
+ CONTEXT WARNING: Approaching limit. Saving current findings.
 ```