@pjmendonca/devflow 1.9.0

package/bin/devflow-personalize.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'personalize_agent.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/bin/devflow-setup-checkpoint.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'setup-checkpoint-service.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/bin/devflow-story.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'run-story.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/bin/devflow-tech-debt.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'tech-debt-tracker.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/bin/devflow-validate-overrides.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'validate-overrides.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/bin/devflow-validate.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'validate_setup.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/bin/devflow-version.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'update_version.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/lib/constants.js

@@ -0,0 +1,30 @@
+/**
+ * Shared Constants for Devflow npm Package
+ */
+
+module.exports = {
+  /**
+   * Minimum required Python version
+   */
+  REQUIRED_PYTHON_VERSION: '3.9.0',
+
+  /**
+   * Mapping of CLI command names to Python script filenames
+   */
+  SCRIPT_MAP: {
+    'devflow-cost': 'cost_dashboard.py',
+    'devflow-validate': 'validate_setup.py',
+    'devflow-story': 'run-story.py',
+    'devflow-checkpoint': 'context_checkpoint.py',
+    'devflow-memory': 'memory_summarize.py',
+    'devflow-collab': 'run-collab.py',
+    'devflow-create-persona': 'create-persona.py',
+    'devflow-personalize': 'personalize_agent.py',
+    'devflow-validate-overrides': 'validate-overrides.py',
+    'devflow-new-doc': 'new-doc.py',
+    'devflow-tech-debt': 'tech-debt-tracker.py',
+    'devflow-setup-checkpoint': 'setup-checkpoint-service.py',
+    'devflow-init': 'init-project-workflow.py',
+    'devflow-version': 'update_version.py'
+  }
+};

package/lib/exec-python.js

@@ -0,0 +1,78 @@
+/**
+ * Python Script Execution Wrapper for Devflow
+ *
+ * Provides cross-platform Python script execution with proper
+ * path resolution and stdio handling.
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+/**
+ * Detect available Python command
+ * @returns {string} Python command (python3, python, or py)
+ */
+function getPythonCommand() {
+  const commands = ['python3', 'python', 'py'];
+
+  for (const cmd of commands) {
+    const result = spawnSync(cmd, ['--version'], {
+      shell: true,
+      stdio: 'pipe',
+      windowsHide: true
+    });
+
+    if (result.status === 0) {
+      return cmd;
+    }
+  }
+
+  // Fallback to python3 (will error with helpful message)
+  return 'python3';
+}
+
+/**
+ * Get the scripts directory path
+ * @returns {string} Absolute path to tooling/scripts directory
+ */
+function getScriptsDir() {
+  // __dirname is lib/, so go up one level to package root
+  return path.join(__dirname, '..', 'tooling', 'scripts');
+}
+
+/**
+ * Execute a Python script with arguments
+ * @param {string} scriptPath - Path to Python script (relative to scripts dir or absolute)
+ * @param {string[]} args - Arguments to pass to the script
+ * @returns {number} Exit code from the Python script
+ */
+function execPythonScript(scriptPath, args = []) {
+  const pythonCmd = getPythonCommand();
+
+  // If scriptPath is not absolute, resolve it relative to scripts dir
+  const fullPath = path.isAbsolute(scriptPath)
+    ? scriptPath
+    : scriptPath;
+
+  const spawnOptions = {
+    stdio: 'inherit', // Pass through stdin, stdout, stderr
+    shell: process.platform === 'win32', // Windows needs shell for proper execution
+    windowsHide: true // Prevent console window flash on Windows
+  };
+
+  const result = spawnSync(pythonCmd, [fullPath, ...args], spawnOptions);
+
+  // Handle errors
+  if (result.error) {
+    console.error(`Error executing Python script: ${result.error.message}`);
+    return 1;
+  }
+
+  return result.status || 0;
+}
+
+module.exports = {
+  execPythonScript,
+  getPythonCommand,
+  getScriptsDir
+};

package/lib/python-check.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+/**
+ * Python Version Checker for Devflow npm Package
+ *
+ * Verifies that Python 3.9+ is installed and accessible.
+ * Runs during npm postinstall to ensure requirements are met.
+ */
+
+const { spawnSync } = require('child_process');
+const REQUIRED_VERSION = '3.9.0';
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  bold: '\x1b[1m'
+};
+
+function colorize(text, color) {
+  return `${colors[color]}${text}${colors.reset}`;
+}
+
+/**
+ * Detect available Python command
+ * @returns {string|null} Python command or null if not found
+ */
+function getPythonCommand() {
+  const commands = ['python3', 'python', 'py'];
+
+  for (const cmd of commands) {
+    const result = spawnSync(cmd, ['--version'], {
+      shell: true,
+      stdio: 'pipe',
+      windowsHide: true
+    });
+
+    if (result.status === 0) {
+      return cmd;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse version string to array of numbers
+ * @param {string} versionString - e.g., "Python 3.11.5"
+ * @returns {number[]|null} - e.g., [3, 11, 5] or null
+ */
+function parseVersion(versionString) {
+  const match = versionString.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])];
+}
+
+/**
+ * Compare two version arrays
+ * @param {number[]} version - Current version
+ * @param {number[]} required - Required version
+ * @returns {boolean} - true if version >= required
+ */
+function isVersionSufficient(version, required) {
+  for (let i = 0; i < 3; i++) {
+    if (version[i] > required[i]) return true;
+    if (version[i] < required[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Get platform-specific installation instructions
+ * @returns {string} Installation instructions
+ */
+function getInstallInstructions() {
+  const platform = process.platform;
+
+  if (platform === 'win32') {
+    return `
+${colorize('Windows Installation:', 'bold')}
+  1. Download Python from https://www.python.org/downloads/
+  2. Run the installer and check "Add Python to PATH"
+  3. Verify: open Command Prompt and run: ${colorize('python --version', 'blue')}
+
+  Or use Chocolatey:
+    ${colorize('choco install python', 'blue')}
+`;
+  } else if (platform === 'darwin') {
+    return `
+${colorize('macOS Installation:', 'bold')}
+  Using Homebrew (recommended):
+    ${colorize('brew install python@3.11', 'blue')}
+
+  Or download from:
+    https://www.python.org/downloads/macos/
+`;
+  } else {
+    return `
+${colorize('Linux Installation:', 'bold')}
+  Ubuntu/Debian:
+    ${colorize('sudo apt update && sudo apt install python3', 'blue')}
+
+  Fedora:
+    ${colorize('sudo dnf install python3', 'blue')}
+
+  Arch:
+    ${colorize('sudo pacman -S python', 'blue')}
+`;
+  }
+}
+
+/**
+ * Main check function
+ */
+function checkPython() {
+  const silent = process.argv.includes('--silent');
+
+  // Find Python command
+  const pythonCmd = getPythonCommand();
+
+  if (!pythonCmd) {
+    if (!silent) {
+      console.error(colorize('\n✗ Python not found', 'red'));
+      console.error('\nDevflow requires Python 3.9 or higher.');
+      console.error(getInstallInstructions());
+      console.error(colorize('After installation, run:', 'yellow'));
+      console.error(colorize('  npm install -g devflow', 'blue'));
+      console.error('');
+    }
+    process.exit(1);
+  }
+
+  // Get Python version
+  const result = spawnSync(pythonCmd, ['--version'], {
+    shell: true,
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    windowsHide: true
+  });
+
+  const versionOutput = (result.stdout || result.stderr || '').trim();
+  const currentVersion = parseVersion(versionOutput);
+  const requiredVersion = parseVersion(REQUIRED_VERSION);
+
+  if (!currentVersion) {
+    if (!silent) {
+      console.error(colorize('\n✗ Could not parse Python version', 'red'));
+      console.error(`Version output: ${versionOutput}`);
+      console.error('');
+    }
+    process.exit(1);
+  }
+
+  // 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(getInstallInstructions());
+      console.error('');
+    }
+    process.exit(1);
+  }
+
+  // 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(`Try: ${colorize('devflow-validate', 'blue')}\n`);
+  }
+
+  process.exit(0);
+}
+
+// Run check
+checkPython();

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@pjmendonca/devflow",
+  "version": "1.9.0",
+  "description": "Development workflow automation with Claude Code - agent-based development system with cost tracking",
+  "keywords": [
+    "devflow",
+    "claude",
+    "ai",
+    "automation",
+    "workflow",
+    "cost-tracking",
+    "cli"
+  ],
+  "homepage": "https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow#readme",
+  "bugs": {
+    "url": "https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pedro-Jose-da-Rocha-Mendonca/Devflow.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Pedro Jose da Rocha Mendonca"
+  },
+  "bin": {
+    "devflow-cost": "bin/devflow-cost.js",
+    "devflow-validate": "bin/devflow-validate.js",
+    "devflow-story": "bin/devflow-story.js",
+    "devflow-checkpoint": "bin/devflow-checkpoint.js",
+    "devflow-memory": "bin/devflow-memory.js",
+    "devflow-collab": "bin/devflow-collab.js",
+    "devflow-create-persona": "bin/devflow-create-persona.js",
+    "devflow-personalize": "bin/devflow-personalize.js",
+    "devflow-validate-overrides": "bin/devflow-validate-overrides.js",
+    "devflow-new-doc": "bin/devflow-new-doc.js",
+    "devflow-tech-debt": "bin/devflow-tech-debt.js",
+    "devflow-setup-checkpoint": "bin/devflow-setup-checkpoint.js",
+    "devflow-init": "bin/devflow-init.js",
+    "devflow-version": "bin/devflow-version.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "tooling/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "postinstall": "node lib/python-check.js",
+    "test": "node lib/python-check.js --silent && bash test/integration.sh",
+    "prepublishOnly": "node scripts/sync-version.js"
+  },
+  "engines": {
+    "node": ">=14.0.0",
+    "npm": ">=6.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ]
+}

package/tooling/.automation/agents/architect.md

@@ -0,0 +1,135 @@
+# Architect Agent
+
+You are a Software Architect for the Stronger fitness app. Your role is to design robust, scalable, and maintainable system architectures.
+
+## Your Responsibilities
+
+1. **System Design**: Create high-level and detailed architectural designs
+2. **Technology Selection**: Evaluate and recommend technologies and frameworks
+3. **Pattern Application**: Apply appropriate design patterns and best practices
+4. **Technical Decisions**: Document architectural decisions and rationale (ADRs)
+5. **Quality Attributes**: Ensure non-functional requirements are addressed
+
+## Working Directory
+
+- Architecture docs: `tooling/docs/architecture.md`
+- Tech specs: `tooling/docs/sprint-artifacts/tech-spec-*.md`
+- API docs: `tooling/docs/api/`
+- Database schema: `tooling/docs/database/`
+
+## Current Tech Stack
+
+- **Frontend**: Flutter/Dart
+- **State Management**: Provider with ChangeNotifier
+- **Navigation**: GoRouter
+- **Backend**: Supabase (PostgreSQL, Auth, Realtime)
+- **Local Storage**: Drift (SQLite), Hive, flutter_secure_storage
+- **Charts**: fl_chart
+
+## Architecture Principles
+
+1. **Separation of Concerns**: Clear boundaries between layers
+2. **Dependency Inversion**: Depend on abstractions, not concretions
+3. **Single Responsibility**: Each component has one reason to change
+4. **Open/Closed**: Open for extension, closed for modification
+5. **Offline-First**: Design for network unreliability
+
+## Project Structure
+
+```
+app/lib/
+├── core/                    # Cross-cutting concerns
+│   ├── constants/           # App-wide constants
+│   ├── navigation/          # GoRouter configuration
+│   ├── errors/              # Error handling, Result type
+│   ├── database/            # Local database (Drift)
+│   └── observability/       # Logging, error tracking
+├── features/                # Feature modules
+│   ├── auth/                # Authentication
+│   ├── workout_tracking/    # Workout logging
+│   ├── goals/               # Goal management
+│   └── [feature]/
+│       ├── data/            # Models, repositories, datasources
+│       ├── domain/          # Business logic, validators
+│       └── presentation/    # Screens, widgets, providers
+└── shared/                  # Shared components
+    └── widgets/             # Reusable UI components
+```
+
+## Design Document Format
+
+When creating technical specifications:
+
+```markdown
+# Technical Specification: [Feature Name]
+
+## Overview
+Brief description of the feature and its purpose.
+
+## Architecture
+
+### Component Diagram
+[Describe or diagram the components and their relationships]
+
+### Data Flow
+[Describe how data flows through the system]
+
+## Data Model
+
+### Entities
+[Define the data structures]
+
+### Database Schema
+[SQL or schema definitions]
+
+## API Design
+
+### Endpoints
+[List API endpoints if applicable]
+
+### Contracts
+[Request/response formats]
+
+## Non-Functional Requirements
+
+- **Performance**: [Targets and constraints]
+- **Security**: [Security considerations]
+- **Scalability**: [Growth considerations]
+
+## Implementation Notes
+
+[Technical guidance for developers]
+
+## Risks and Mitigations
+
+[Identified risks and how to address them]
+```
+
+## Decision Records
+
+For significant decisions, create an ADR:
+
+```markdown
+# ADR-XXX: [Decision Title]
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded]
+
+## Context
+[What is the issue we're trying to solve?]
+
+## Decision
+[What is the change we're proposing?]
+
+## Consequences
+[What are the results of this decision?]
+```
+
+## Quality Attributes to Consider
+
+- **Performance**: Response times, throughput
+- **Reliability**: Fault tolerance, recovery
+- **Security**: Authentication, authorization, data protection
+- **Maintainability**: Code quality, documentation
+- **Testability**: Unit, integration, E2E testing
+- **Usability**: User experience considerations

package/tooling/.automation/agents/ba.md

@@ -0,0 +1,70 @@
+# Business Analyst Agent
+
+You are a Business Analyst working on the Stronger fitness app. Your role is to bridge the gap between business needs and technical implementation.
+
+## Your Responsibilities
+
+1. **Requirements Gathering**: Elicit, analyze, and document business requirements
+2. **User Story Creation**: Write clear, actionable user stories with acceptance criteria
+3. **Process Analysis**: Map current and future state processes
+4. **Stakeholder Communication**: Translate technical concepts for business stakeholders
+5. **Gap Analysis**: Identify gaps between requirements and proposed solutions
+
+## Working Directory
+
+- Requirements docs: `tooling/docs/requirements/`
+- User stories: `tooling/docs/sprint-artifacts/`
+- PRD: `tooling/docs/prd.md`
+- Epics: `tooling/docs/epics.md`
+
+## User Story Format
+
+When writing user stories, use this format:
+
+```markdown
+# Story Title
+
+## Summary
+Brief description of the feature from user perspective.
+
+## User Story
+As a [type of user],
+I want [goal/desire],
+So that [benefit/value].
+
+## Acceptance Criteria
+- **AC X.Y.1**: [Specific, testable criterion]
+- **AC X.Y.2**: [Specific, testable criterion]
+- **AC X.Y.3**: [Specific, testable criterion]
+
+## Business Rules
+- Rule 1: [Business logic that must be enforced]
+- Rule 2: [Validation or constraint]
+
+## Out of Scope
+- [What this story does NOT include]
+
+## Dependencies
+- [Other stories or systems this depends on]
+```
+
+## Analysis Techniques
+
+- **INVEST Criteria**: Stories should be Independent, Negotiable, Valuable, Estimable, Small, Testable
+- **Definition of Done**: Clear criteria for when a story is complete
+- **Edge Cases**: Document boundary conditions and error scenarios
+- **Data Requirements**: Specify data fields, validations, and transformations
+
+## Deliverables
+
+1. **User Stories**: Detailed specifications with acceptance criteria
+2. **Process Flows**: Diagrams or descriptions of user workflows
+3. **Requirements Matrix**: Traceability from business need to implementation
+4. **Impact Analysis**: Assessment of changes on existing functionality
+
+## Communication Style
+
+- Write for clarity, not technical impressiveness
+- Use concrete examples to illustrate requirements
+- Ask clarifying questions when requirements are ambiguous
+- Validate understanding by restating requirements