@pjmendonca/devflow 1.18.0 → 1.20.0

package/.claude/skills/dashboard/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: dashboard
+description: Launch live status dashboard in a terminal
+---
+
+# Live Dashboard Skill
+
+Launch or provide instructions for the Devflow live status dashboard - a real-time display of context usage, cost tracking, and agent activity.
+
+## Usage
+
+```
+/dashboard [story-key] [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| story-key | Story to monitor (default: 'default') |
+| --refresh N | Refresh interval in seconds (default: 0.5) |
+| --compact | Single-line compact mode |
+| --width N | Dashboard width (default: 70) |
+
+## Prompt
+
+You are helping the user launch the Devflow live dashboard.
+
+**Arguments:** $ARGUMENTS
+
+### Dashboard Launch Instructions
+
+The live dashboard is a terminal-based real-time display that needs to run in a separate terminal to show continuous updates while you work.
+
+**Option 1: VS Code Split Terminal (Recommended)**
+
+Tell the user:
+
+1. Open the VS Code integrated terminal (Ctrl+` or Cmd+`)
+2. Click the "Split Terminal" button (or press Cmd+Shift+5 / Ctrl+Shift+5)
+3. In the new terminal pane, run:
+
+```bash
+python3 tooling/scripts/live_dashboard.py $ARGUMENTS
+```
+
+Or if using npm:
+```bash
+npx devflow dashboard $ARGUMENTS
+```
+
+**Option 2: Separate Terminal Window**
+
+For a floating dashboard window:
+
+```bash
+# Open a new terminal and run:
+cd [project-root] && python3 tooling/scripts/live_dashboard.py $ARGUMENTS
+```
+
+**Option 3: Compact Mode (less screen space)**
+
+For minimal display:
+```bash
+python3 tooling/scripts/live_dashboard.py --compact $ARGUMENTS
+```
+
+### Dashboard Features
+
+The dashboard displays:
+
+```
++------------------------------------------------------------------+
+|  DEVFLOW LIVE DASHBOARD                          Updated: HH:MM  |
++------------------------------------------------------------------+
+|  ACTIVITY                                                        |
+|  Agent: DEV [2/3] Development (3:45)                            |
+|  Task: Implementing user authentication                          |
++------------------------------------------------------------------+
+|  CONTEXT                                                         |
+|  Usage: [================--------]  65.2% ^                      |
+|  Tokens: 130.4K/200K  ~14 exchanges left                        |
++------------------------------------------------------------------+
+|  COST                                                            |
+|  Budget: [====--------------------]  12.3%                       |
+|  Spent: $1.85 / $15.00  In: 45.2K  Out: 12.1K                   |
++------------------------------------------------------------------+
+|  RECENT                                                          |
+|  > +3.2K tokens (45s ago)                                       |
+|  > +2.8K tokens (1m ago)                                        |
++------------------------------------------------------------------+
+```
+
+- **Activity**: Current agent, phase, task, and elapsed time
+- **Context**: Visual progress bar with trend indicator and remaining exchanges
+- **Cost**: Budget usage with token breakdown
+- **Recent**: Token history showing recent activity
+
+### Color Coding
+
+- Green: Safe levels (< 50% context, < 75% budget)
+- Yellow: Caution (50-75% context, 75-90% budget)
+- Red: Critical (> 75% context, > 90% budget)
+
+### Tips
+
+1. **High refresh rate**: Use `--refresh 0.25` for faster updates
+2. **Narrow terminal**: Use `--width 60` for smaller panes
+3. **Minimal mode**: Use `--compact` for single-line status
+4. **Stop dashboard**: Press Ctrl+C to exit
+
+### If No Data Shows
+
+The dashboard reads from:
+- Context state: `tooling/.automation/context/context_[story-key].json`
+- Cost data: `tooling/.automation/costs/sessions/*.json`
+
+If these files don't exist yet, run a story or use `/develop` to generate tracking data.

package/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.20.0] - 2026-01-16
+
+### Fixed
+- **Import Error** - Fixed Python stdlib `platform` module conflict in multiple scripts
+  - `run-collab.py`, `run-story.py`, `new-doc.py`, `setup-checkpoint-service.py` now use `from lib.platform import`
+  - `swarm_orchestrator.py`, `pair_programming.py`, `cost_display.py` now prioritize lib.platform over stdlib
+  - Resolves `ImportError: cannot import name 'IS_MACOS' from 'platform'` on Python 3.14+
+
+### Added
+- **Live Dashboard** - Real-time terminal status display for monitoring Devflow sessions
+  - Rich ASCII dashboard with box-drawing characters and color-coded progress bars
+  - Shows context usage, cost tracking, current agent/activity, and token history
+  - Configurable refresh rate (default 0.5s) for responsive updates
+  - Compact single-line mode with `--compact` flag
+  - Run via `devflow dashboard` or `python3 tooling/scripts/live_dashboard.py`
+  - New `/dashboard` skill with instructions for VS Code split terminal setup
+
+- **Swarm Command** - Added `devflow swarm` CLI command for multi-agent swarm mode
+  - New `bin/devflow-swarm.js` wrapper that calls run-collab.py with --swarm flag
+  - Added to devflow.js dispatcher and package.json bin entries
+
+## [1.19.0] - 2026-01-03
+
+### Added
+- **Story Discovery Phase in Init Wizard** - Optional Phase 4 for quick story brainstorming
+  - Vision discovery with problem, users, success metrics, and competitive advantage
+  - Core feature identification with comma-separated input
+  - First sprint planning with story proposals
+  - Automatic story file generation in `tooling/docs/stories/`
+  - Integration with sprint-status.yaml for backlog tracking
+
+- **Brainstorm Skill** - Full workshop for product discovery and story creation
+  - `/brainstorm` command for 30-minute comprehensive workshops
+  - `--quick` mode for 10-minute vision + features session
+  - `--journey` mode for focused user journey mapping
+  - `--features` mode for rapid feature brainstorming
+  - `--decompose EPIC` to break epics into stories
+  - `--prioritize` to re-prioritize existing backlog
+
+- **Brainstorming Techniques Guide** - Reference documentation for discovery methods
+  - Guided Discovery (Socratic method) with vision and feature questions
+  - User Journey Mapping with 5-stage framework (Trigger, Entry, Core, Success, Retention)
+  - Rapid Feature List with MoSCoW prioritization
+  - Story Decomposition with INVEST criteria
+  - RICE scoring and Impact/Effort matrix for prioritization
+
+- **Story Template** - New `tooling/docs/templates/story.md` for feature stories
+  - User story format with acceptance criteria
+  - Priority and effort sizing (XS/S/M/L/XL)
+  - Technical notes, business rules, and dependencies
+  - Testing strategy and definition of done
+
+- **Stories Directory** - `tooling/docs/stories/` for story file storage
+  - Stories use format: `STORY-{sprint}-{number}-{slug}.md`
+  - Integrated with sprint-status.yaml tracking
+
+### Changed
+- **Init Wizard** - Now 6 phases (added Story Discovery as Phase 4)
+  - Quick Mode skips story discovery, recommends `/brainstorm` after setup
+  - Phase 6 summary includes story count and brainstorm command reference
+  - Directory structure now includes `tooling/docs/stories/` and `tooling/docs/templates/`
+
 ## [1.18.0] - 2025-12-30
 
 ### Added

package/README.md

@@ -747,7 +747,7 @@ Free to use in commercial and personal projects.
 
 
 <!-- VERSION_START - Auto-updated by update_version.py -->
-**Version**: 1.18.0
+**Version**: 1.20.0
 **Status**: Production Ready
-**Last Updated**: 2025-12-30
+**Last Updated**: 2026-01-16
 <!-- VERSION_END -->

package/bin/devflow-dashboard.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(), 'live_dashboard.py');
+const args = process.argv.slice(2);
+
+const exitCode = execPythonScript(scriptPath, args);
+process.exit(exitCode);

package/bin/devflow-swarm.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execPythonScript, getScriptsDir } = require('../lib/exec-python');
+
+const scriptPath = path.join(getScriptsDir(), 'run-collab.py');
+const args = process.argv.slice(2);
+
+// Prepend --swarm flag to run in swarm mode
+const exitCode = execPythonScript(scriptPath, ['--swarm', ...args]);
+process.exit(exitCode);

package/bin/devflow.js

@@ -6,6 +6,8 @@ const commands = {
   'install': 'Install Devflow into your project',
   'story': 'Run full story pipeline (context + dev + review)',
   'collab': 'Run collaborative story with mode selection',
+  'swarm': 'Run multi-agent swarm mode (debate/consensus)',
+  'dashboard': 'Live status dashboard (context, cost, activity)',
   'checkpoint': 'Create or restore context checkpoints',
   'memory': 'View or query shared agent memory',
   'cost': 'View cost dashboard and spending analytics',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pjmendonca/devflow",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Development workflow automation with Claude Code - agent-based development system with cost tracking",
   "keywords": [
     "devflow",
@@ -33,6 +33,8 @@
     "devflow-checkpoint": "bin/devflow-checkpoint.js",
     "devflow-memory": "bin/devflow-memory.js",
     "devflow-collab": "bin/devflow-collab.js",
+    "devflow-swarm": "bin/devflow-swarm.js",
+    "devflow-dashboard": "bin/devflow-dashboard.js",
     "devflow-create-persona": "bin/devflow-create-persona.js",
     "devflow-personalize": "bin/devflow-personalize.js",
     "devflow-validate-overrides": "bin/devflow-validate-overrides.js",

package/tooling/.automation/memory/knowledge/kg_integration-test.json

@@ -1,6 +1,6 @@
 {
   "story_key": "integration-test",
-  "last_updated": "2025-12-30T10:50:21.128645",
+  "last_updated": "2026-01-16T12:33:48.829767",
   "decisions": {},
   "topic_index": {},
   "handoffs": [
@@ -931,6 +931,121 @@
         "Implement the required functionality",
         "Write tests for the implementation"
       ]
+    },
+    {
+      "id": "handoff_72587485",
+      "timestamp": "2026-01-03T14:30:38.051699",
+      "from_agent": "SM",
+      "to_agent": "DEV",
+      "story_key": "integration-test",
+      "summary": "Ready for implementation",
+      "key_decisions": [],
+      "blockers_resolved": [],
+      "watch_out_for": [],
+      "files_touched": [
+        ".claude/commands/brainstorm.md",
+        ".claude/commands/init.md",
+        ".claude/skills/brainstorm/SKILL.md",
+        ".gitignore",
+        "CHANGELOG.md",
+        "README.md",
+        "package.json",
+        "pyproject.toml",
+        "tooling/docs/stories/.gitkeep",
+        "tooling/docs/templates/brainstorm-guide.md",
+        "tooling/docs/templates/story.md",
+        "tooling/scripts/lib/__init__.py"
+      ],
+      "next_steps": [
+        "Review the acceptance criteria in the story context",
+        "Examine the 12 files that have context",
+        "Implement the required functionality",
+        "Write tests for the implementation"
+      ]
+    },
+    {
+      "id": "handoff_cb6d7c7a",
+      "timestamp": "2026-01-16T12:33:30.919040",
+      "from_agent": "SM",
+      "to_agent": "DEV",
+      "story_key": "integration-test",
+      "summary": "Ready for implementation",
+      "key_decisions": [],
+      "blockers_resolved": [],
+      "watch_out_for": [],
+      "files_touched": [
+        ".claude/commands/brainstorm.md",
+        ".claude/commands/init.md",
+        ".claude/skills/brainstorm/SKILL.md",
+        ".claude/skills/dashboard/SKILL.md",
+        "CHANGELOG.md",
+        "README.md",
+        "bin/devflow-dashboard.js",
+        "bin/devflow-swarm.js",
+        "bin/devflow.js",
+        "package.json",
+        "pyproject.toml",
+        "tooling/docs/stories/.gitkeep",
+        "tooling/docs/templates/brainstorm-guide.md",
+        "tooling/docs/templates/story.md",
+        "tooling/scripts/lib/__init__.py",
+        "tooling/scripts/lib/cost_display.py",
+        "tooling/scripts/lib/pair_programming.py",
+        "tooling/scripts/lib/swarm_orchestrator.py",
+        "tooling/scripts/live_dashboard.py",
+        "tooling/scripts/new-doc.py",
+        "tooling/scripts/run-collab.py",
+        "tooling/scripts/run-story.py",
+        "tooling/scripts/setup-checkpoint-service.py"
+      ],
+      "next_steps": [
+        "Review the acceptance criteria in the story context",
+        "Examine the 23 files that have context",
+        "Implement the required functionality",
+        "Write tests for the implementation"
+      ]
+    },
+    {
+      "id": "handoff_a2389911",
+      "timestamp": "2026-01-16T12:33:48.829611",
+      "from_agent": "SM",
+      "to_agent": "DEV",
+      "story_key": "integration-test",
+      "summary": "Ready for implementation",
+      "key_decisions": [],
+      "blockers_resolved": [],
+      "watch_out_for": [],
+      "files_touched": [
+        ".claude/commands/brainstorm.md",
+        ".claude/commands/init.md",
+        ".claude/skills/brainstorm/SKILL.md",
+        ".claude/skills/dashboard/SKILL.md",
+        "CHANGELOG.md",
+        "README.md",
+        "bin/devflow-dashboard.js",
+        "bin/devflow-swarm.js",
+        "bin/devflow.js",
+        "package.json",
+        "pyproject.toml",
+        "tooling/docs/stories/.gitkeep",
+        "tooling/docs/templates/brainstorm-guide.md",
+        "tooling/docs/templates/story.md",
+        "tooling/scripts/lib/__init__.py",
+        "tooling/scripts/lib/cost_display.py",
+        "tooling/scripts/lib/pair_programming.py",
+        "tooling/scripts/lib/swarm_orchestrator.py",
+        "tooling/scripts/live_dashboard.py",
+        "tooling/scripts/new-doc.py",
+        "tooling/scripts/run-collab.py",
+        "tooling/scripts/run-story.py",
+        "tooling/scripts/setup-checkpoint-service.py"
+      ],
+      "next_steps": [
+        "Review the acceptance criteria in the story context",
+        "Examine the 23 files that have context",
+        "Implement the required functionality",
+        "Write tests for the implementation"
+      ]
     }
   ]
 }