@pjmendonca/devflow 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.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.19.0
 **Status**: Production Ready
-**Last Updated**: 2025-12-30
+**Last Updated**: 2026-01-03
 <!-- VERSION_END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pjmendonca/devflow",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Development workflow automation with Claude Code - agent-based development system with cost tracking",
   "keywords": [
     "devflow",

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-03T14:30:38.051845",
   "decisions": {},
   "topic_index": {},
   "handoffs": [
@@ -931,6 +931,37 @@
         "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"
+      ]
     }
   ]
 }

package/tooling/.automation/memory/knowledge/kg_test-story.json

@@ -1,6 +1,6 @@
 {
   "story_key": "test-story",
-  "last_updated": "2025-12-30T10:50:21.104384",
+  "last_updated": "2026-01-03T14:30:38.027249",
   "decisions": {
     "dec_c5690ae1": {
       "id": "dec_c5690ae1",
@@ -241,6 +241,16 @@
       "context": {},
       "supersedes": null,
       "status": "active"
+    },
+    "dec_c76c3450": {
+      "id": "dec_c76c3450",
+      "timestamp": "2026-01-03T14:30:38.009460",
+      "agent": "DEV",
+      "topic": "approach",
+      "decision": "Use REST API",
+      "context": {},
+      "supersedes": null,
+      "status": "active"
     }
   },
   "topic_index": {
@@ -268,7 +278,8 @@
       "dec_bbc8b2a9",
       "dec_1f8bb74c",
       "dec_9df46791",
-      "dec_6c156148"
+      "dec_6c156148",
+      "dec_c76c3450"
     ]
   },
   "handoffs": [
@@ -4002,6 +4013,103 @@
         "Implement the required functionality",
         "Write tests for the implementation"
       ]
+    },
+    {
+      "id": "handoff_2edf60e3",
+      "timestamp": "2026-01-03T14:30:38.005413",
+      "from_agent": "SM",
+      "to_agent": "DEV",
+      "story_key": "test-story",
+      "summary": "Created story context",
+      "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_31bd54b7",
+      "timestamp": "2026-01-03T14:30:38.017799",
+      "from_agent": "DEV",
+      "to_agent": "REVIEWER",
+      "story_key": "test-story",
+      "summary": "Implementation complete",
+      "key_decisions": [
+        "approach: Use REST API"
+      ],
+      "blockers_resolved": [],
+      "watch_out_for": [
+        "Watch out for rate limits"
+      ],
+      "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 12 changed files",
+        "Check for code quality and best practices",
+        "Verify test coverage",
+        "Provide actionable feedback"
+      ]
+    },
+    {
+      "id": "handoff_3714f8e3",
+      "timestamp": "2026-01-03T14:30:38.027089",
+      "from_agent": "SM",
+      "to_agent": "DEV",
+      "story_key": "test-story",
+      "summary": "Ready for development",
+      "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"
+      ]
     }
   ]
 }

package/tooling/.automation/memory/shared/shared_integration-test.json

@@ -1,6 +1,6 @@
 {
   "story_key": "integration-test",
-  "last_updated": "2025-12-30T10:50:21.129144",
+  "last_updated": "2026-01-03T14:30:38.052354",
   "entries": [
     {
       "id": "mem_1bf0cedf",
@@ -229,6 +229,18 @@
       ],
       "story_key": "integration-test",
       "references": []
+    },
+    {
+      "id": "mem_bb260d11",
+      "timestamp": "2026-01-03T14:30:38.052311",
+      "agent": "SM",
+      "content": "Handed off to DEV: Ready for implementation",
+      "tags": [
+        "handoff",
+        "dev"
+      ],
+      "story_key": "integration-test",
+      "references": []
     }
   ]
 }

package/tooling/.automation/memory/shared/shared_test-story.json

@@ -1,6 +1,6 @@
 {
   "story_key": "test-story",
-  "last_updated": "2025-12-30T10:50:21.106158",
+  "last_updated": "2026-01-03T14:30:38.028834",
   "entries": [
     {
       "id": "mem_94d28071",
@@ -865,6 +865,42 @@
       ],
       "story_key": "test-story",
       "references": []
+    },
+    {
+      "id": "mem_c4372819",
+      "timestamp": "2026-01-03T14:30:38.007244",
+      "agent": "SM",
+      "content": "Handed off to DEV: Created story context",
+      "tags": [
+        "handoff",
+        "dev"
+      ],
+      "story_key": "test-story",
+      "references": []
+    },
+    {
+      "id": "mem_1b8e1be0",
+      "timestamp": "2026-01-03T14:30:38.019647",
+      "agent": "DEV",
+      "content": "Handed off to REVIEWER: Implementation complete",
+      "tags": [
+        "handoff",
+        "reviewer"
+      ],
+      "story_key": "test-story",
+      "references": []
+    },
+    {
+      "id": "mem_4b3bf56a",
+      "timestamp": "2026-01-03T14:30:38.028794",
+      "agent": "SM",
+      "content": "Handed off to DEV: Ready for development",
+      "tags": [
+        "handoff",
+        "dev"
+      ],
+      "story_key": "test-story",
+      "references": []
     }
   ]
 }

package/tooling/.automation/memory/shared/shared_test.json

@@ -1,6 +1,6 @@
 {
   "story_key": "test",
-  "last_updated": "2025-12-30T10:50:21.313021",
+  "last_updated": "2026-01-03T14:30:38.235634",
   "entries": [
     {
       "id": "mem_459b587a",
@@ -1249,6 +1249,84 @@
       ],
       "story_key": "test",
       "references": []
+    },
+    {
+      "id": "mem_8c955b1c",
+      "timestamp": "2026-01-03T14:30:38.226838",
+      "agent": "VALIDATOR",
+      "content": "Validation pass: 2 gates, 2 passed",
+      "tags": [
+        "validation",
+        "tier-1",
+        "pass"
+      ],
+      "story_key": "test",
+      "references": []
+    },
+    {
+      "id": "mem_555dde17",
+      "timestamp": "2026-01-03T14:30:38.228560",
+      "agent": "VALIDATOR",
+      "content": "Validation fail: 2 gates, 1 passed",
+      "tags": [
+        "validation",
+        "tier-1",
+        "fail"
+      ],
+      "story_key": "test",
+      "references": []
+    },
+    {
+      "id": "mem_3858cf39",
+      "timestamp": "2026-01-03T14:30:38.229681",
+      "agent": "VALIDATOR",
+      "content": "Validation fail: 1 gates, 0 passed",
+      "tags": [
+        "validation",
+        "tier-1",
+        "fail"
+      ],
+      "story_key": "test",
+      "references": []
+    },
+    {
+      "id": "mem_0f015277",
+      "timestamp": "2026-01-03T14:30:38.230833",
+      "agent": "VALIDATOR",
+      "content": "Validation pass: 1 gates, 1 passed",
+      "tags": [
+        "validation",
+        "tier-1",
+        "pass"
+      ],
+      "story_key": "test",
+      "references": []
+    },
+    {
+      "id": "mem_5ece956e",
+      "timestamp": "2026-01-03T14:30:38.231980",
+      "agent": "VALIDATOR",
+      "content": "Validation pass: 1 gates, 1 passed",
+      "tags": [
+        "validation",
+        "tier-3",
+        "pass"
+      ],
+      "story_key": "test",
+      "references": []
+    },
+    {
+      "id": "mem_4179d48f",
+      "timestamp": "2026-01-03T14:30:38.235600",
+      "agent": "VALIDATOR",
+      "content": "Validation fail: 1 gates, 0 passed",
+      "tags": [
+        "validation",
+        "tier-1",
+        "fail"
+      ],
+      "story_key": "test",
+      "references": []
     }
   ]
 }

package/tooling/.automation/memory/shared/shared_validation-check.json

@@ -1,6 +1,6 @@
 {
   "story_key": "validation-check",
-  "last_updated": "2025-12-30T10:50:21.453267",
+  "last_updated": "2026-01-03T14:30:38.341965",
   "entries": [
     {
       "id": "mem_b27527fa",
@@ -222,6 +222,19 @@
       ],
       "story_key": "validation-check",
       "references": []
+    },
+    {
+      "id": "mem_0aa2a024",
+      "timestamp": "2026-01-03T14:30:38.341907",
+      "agent": "VALIDATOR",
+      "content": "Validation pass: 4 gates, 4 passed",
+      "tags": [
+        "validation",
+        "tier-3",
+        "pass"
+      ],
+      "story_key": "validation-check",
+      "references": []
     }
   ]
 }

package/tooling/.automation/validation/history/2026-01-03_val_1287a74c.json

@@ -0,0 +1,41 @@
+{
+  "id": "val_1287a74c",
+  "timestamp": "2026-01-03T14:30:38.228447",
+  "story_key": "test",
+  "tier": 1,
+  "gate_results": [
+    {
+      "gate_name": "pass",
+      "result": "pass",
+      "message": "Validation passed",
+      "duration_ms": 0.0,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    },
+    {
+      "gate_name": "fail",
+      "result": "fail",
+      "message": "Validation failed",
+      "duration_ms": 0.0,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    }
+  ],
+  "overall_result": "fail",
+  "total_duration_ms": 0.004291534423828125,
+  "passed": false,
+  "context": {
+    "story_key": "test",
+    "iteration": 0,
+    "max_iterations": 3,
+    "accumulated_issues": [],
+    "accumulated_fixes": [],
+    "cost_so_far": 0.0,
+    "time_elapsed_seconds": 0.0,
+    "phase": "",
+    "from_agent": "",
+    "to_agent": ""
+  }
+}

package/tooling/.automation/validation/history/2026-01-03_val_3b24071f.json

@@ -0,0 +1,32 @@
+{
+  "id": "val_3b24071f",
+  "timestamp": "2026-01-03T14:30:38.229579",
+  "story_key": "test",
+  "tier": 1,
+  "gate_results": [
+    {
+      "gate_name": "block",
+      "result": "fail",
+      "message": "Validation failed",
+      "duration_ms": 0.00095367431640625,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    }
+  ],
+  "overall_result": "fail",
+  "total_duration_ms": 0.017881393432617188,
+  "passed": false,
+  "context": {
+    "story_key": "test",
+    "iteration": 0,
+    "max_iterations": 3,
+    "accumulated_issues": [],
+    "accumulated_fixes": [],
+    "cost_so_far": 0.0,
+    "time_elapsed_seconds": 0.0,
+    "phase": "",
+    "from_agent": "",
+    "to_agent": ""
+  }
+}

package/tooling/.automation/validation/history/2026-01-03_val_44d77573.json

@@ -0,0 +1,32 @@
+{
+  "id": "val_44d77573",
+  "timestamp": "2026-01-03T14:30:38.230732",
+  "story_key": "test",
+  "tier": 1,
+  "gate_results": [
+    {
+      "gate_name": "test",
+      "result": "pass",
+      "message": "Validation passed",
+      "duration_ms": 0.0,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    }
+  ],
+  "overall_result": "pass",
+  "total_duration_ms": 0.00286102294921875,
+  "passed": true,
+  "context": {
+    "story_key": "test",
+    "iteration": 0,
+    "max_iterations": 3,
+    "accumulated_issues": [],
+    "accumulated_fixes": [],
+    "cost_so_far": 0.0,
+    "time_elapsed_seconds": 0.0,
+    "phase": "",
+    "from_agent": "",
+    "to_agent": ""
+  }
+}

package/tooling/.automation/validation/history/2026-01-03_val_5b31dc51.json

@@ -0,0 +1,32 @@
+{
+  "id": "val_5b31dc51",
+  "timestamp": "2026-01-03T14:30:38.231882",
+  "story_key": "test",
+  "tier": 3,
+  "gate_results": [
+    {
+      "gate_name": "test",
+      "result": "pass",
+      "message": "Validation passed",
+      "duration_ms": 0.00095367431640625,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    }
+  ],
+  "overall_result": "pass",
+  "total_duration_ms": 0.00286102294921875,
+  "passed": true,
+  "context": {
+    "story_key": "test",
+    "iteration": 0,
+    "max_iterations": 3,
+    "accumulated_issues": [],
+    "accumulated_fixes": [],
+    "cost_so_far": 0.0,
+    "time_elapsed_seconds": 0.0,
+    "phase": "",
+    "from_agent": "",
+    "to_agent": ""
+  }
+}

package/tooling/.automation/validation/history/2026-01-03_val_74267244.json

@@ -0,0 +1,32 @@
+{
+  "id": "val_74267244",
+  "timestamp": "2026-01-03T14:30:38.235432",
+  "story_key": "test",
+  "tier": 1,
+  "gate_results": [
+    {
+      "gate_name": "fail_gate",
+      "result": "fail",
+      "message": "Validation failed",
+      "duration_ms": 0.0,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    }
+  ],
+  "overall_result": "fail",
+  "total_duration_ms": 0.0040531158447265625,
+  "passed": false,
+  "context": {
+    "story_key": "test",
+    "iteration": 0,
+    "max_iterations": 3,
+    "accumulated_issues": [],
+    "accumulated_fixes": [],
+    "cost_so_far": 0.0,
+    "time_elapsed_seconds": 0.0,
+    "phase": "",
+    "from_agent": "",
+    "to_agent": ""
+  }
+}

package/tooling/.automation/validation/history/2026-01-03_val_8b2d95c7.json

@@ -0,0 +1,59 @@
+{
+  "id": "val_8b2d95c7",
+  "timestamp": "2026-01-03T14:30:38.341537",
+  "story_key": "validation-check",
+  "tier": 3,
+  "gate_results": [
+    {
+      "gate_name": "tests_pass",
+      "result": "pass",
+      "message": "Validation passed",
+      "duration_ms": 548.0339527130127,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    },
+    {
+      "gate_name": "lint_clean",
+      "result": "pass",
+      "message": "Validation passed",
+      "duration_ms": 14.641046524047852,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    },
+    {
+      "gate_name": "types_valid",
+      "result": "pass",
+      "message": "Validation passed",
+      "duration_ms": 14.327049255371094,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    },
+    {
+      "gate_name": "version_synced",
+      "result": "pass",
+      "message": "Validation passed",
+      "duration_ms": 28.564929962158203,
+      "retry_count": 0,
+      "auto_fixed": false,
+      "details": {}
+    }
+  ],
+  "overall_result": "pass",
+  "total_duration_ms": 605.6423187255859,
+  "passed": true,
+  "context": {
+    "story_key": "validation-check",
+    "iteration": 0,
+    "max_iterations": 3,
+    "accumulated_issues": [],
+    "accumulated_fixes": [],
+    "cost_so_far": 0.0,
+    "time_elapsed_seconds": 0.0,
+    "phase": "tier_3",
+    "from_agent": "",
+    "to_agent": ""
+  }
+}