@pjmendonca/devflow 1.18.0 → 1.20.0

package/.claude/commands/brainstorm.md

@@ -0,0 +1,28 @@
+---
+description: Run story brainstorming workshop
+argument-hint: [--quick|--journey|--features|--decompose EPIC|--prioritize]
+---
+
+# Brainstorm Command
+
+Run the brainstorm skill for story discovery and backlog creation.
+
+Use the Skill tool to invoke the brainstorm skill with the provided arguments:
+
+```
+skill: brainstorm
+args: $ARGUMENTS
+```
+
+If no arguments provided, run the full workshop mode.
+
+## Quick Reference
+
+| Mode | Time | Description |
+|------|------|-------------|
+| (default) | 30 min | Full workshop: vision, features, journey, decomposition, planning |
+| --quick | 10 min | Vision + 5 key features |
+| --journey | 15 min | Focus on user journey mapping |
+| --features | 15 min | Focus on rapid feature brainstorming |
+| --decompose EPIC | 10 min | Break down an epic into stories |
+| --prioritize | 5 min | Re-prioritize existing backlog |

package/.claude/commands/init.md

@@ -89,7 +89,96 @@ If yes, briefly explain each agent and offer quick customization:
 
 Offer template options for each if they want customization.
 
-### Phase 4: Generate Configuration
+### Phase 4: Story Discovery (Optional)
+
+Ask if they want to brainstorm initial stories:
+```
+Would you like to brainstorm your first stories now?
+```
+
+Options:
+- **Quick Discovery** (5 min) - Vision and 3-5 key features for sprint 1
+- **Skip for now** - Run `/brainstorm` later for a full workshop session
+
+If they choose Quick Discovery, run through this flow:
+
+**Step 1: Vision (2 questions)**
+
+Use AskUserQuestion with open text:
+```
+What problem are you solving with this project?
+```
+
+Then:
+```
+Who is your primary user? (e.g., "developers", "fitness enthusiasts", "small business owners")
+```
+
+**Step 2: Core Features (1 question)**
+
+```
+What are the 3-5 core features this project needs?
+(Enter as a comma-separated list)
+```
+
+**Step 3: First Sprint Planning**
+
+Based on their answers, propose 3-5 stories for Sprint 1:
+
+```
+Based on your vision, here's a proposed Sprint 1:
+
+1-1-{feature-slug}: {Feature description}
+1-2-{feature-slug}: {Feature description}
+1-3-{feature-slug}: {Feature description}
+
+Would you like to:
+- Accept these stories
+- Modify the list
+- Add more details to each
+```
+
+**Step 4: Generate Story Files**
+
+For each accepted story, create:
+1. Entry in `tooling/docs/sprint-status.yaml`
+2. Story file in `tooling/docs/stories/STORY-{key}.md`
+
+Use the story template from `tooling/docs/templates/story.md`.
+
+Story file example:
+```markdown
+# STORY-1-1-user-login
+
+**Type**: Feature
+**Status**: backlog
+**Sprint**: 1
+**Priority**: P1 (High)
+**Effort**: M
+**Created**: {date}
+
+---
+
+## Summary
+
+{One-line based on user's feature description}
+
+## User Story
+
+As a **{user type from step 1}**,
+I want **{goal extracted from feature}**,
+So that **{benefit based on problem statement}**.
+
+## Acceptance Criteria
+
+- [ ] **AC-1**: {Generated based on feature}
+- [ ] **AC-2**: {Generated based on feature}
+- [ ] **AC-3**: {Generated based on feature}
+```
+
+**Note**: For deeper brainstorming with user journeys, prioritization frameworks, and story decomposition, recommend running `/brainstorm` after setup.
+
+### Phase 5: Generate Configuration
 
 Based on the answers, create all necessary files:
 
@@ -103,6 +192,8 @@ tooling/.automation/memory/shared/
 tooling/.automation/overrides/
 tooling/scripts/lib/
 tooling/docs/
+tooling/docs/stories/
+tooling/docs/templates/
 ```
 
 2. **Generate `tooling/.automation/config.sh`** with the collected preferences
@@ -121,7 +212,7 @@ tooling/docs/
 
 5. **Generate workflow README** in `tooling/README.md`
 
-### Phase 5: Next Steps
+### Phase 6: Next Steps
 
 After setup is complete, provide a summary:
 
@@ -133,18 +224,22 @@ Configuration created:
 - Workflow: {workflow_mode}
 - Models: {model_strategy}
 - Currency: {currency}
+- Stories: {story_count} stories in Sprint 1 (if created)
 
 Quick Start:
-1. Create your first story: /story create "Add login feature"
-2. Run development: /develop 1-1
-3. Run review: /review 1-1
-4. Check costs: /costs
+1. Brainstorm more stories: /brainstorm
+2. Run full story pipeline: /story 1-1-feature-name
+3. Development only: /develop 1-1-feature-name
+4. Review only: /review 1-1-feature-name
+5. Check costs: /costs
 
 Useful Commands:
+- /brainstorm - Full workshop for story discovery
 - /personalize - Customize agent behavior
 - /memory - View shared agent memory
 - /checkpoint - Save/restore context
 
+Your Stories: tooling/docs/stories/
 Documentation: tooling/README.md
 ```
 
@@ -156,6 +251,7 @@ If the user runs `/init --quick`, skip optional questions and use smart defaults
 - Use "Balanced" model strategy (Opus for dev, Sonnet for planning)
 - Use USD for currency
 - Skip agent personalization
+- Skip story discovery (recommend `/brainstorm` after setup)
 
 ## Important Guidelines
 

package/.claude/skills/brainstorm/SKILL.md

@@ -0,0 +1,531 @@
+---
+name: brainstorm
+description: Full workshop for story discovery, user journey mapping, and backlog creation (project)
+---
+
+# Brainstorm Skill
+
+A comprehensive product discovery workshop that guides users through vision definition, feature brainstorming, user journey mapping, and story creation.
+
+## Usage
+
+```
+/brainstorm [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| --quick | Quick mode: Vision + 5 features (10 min) |
+| --journey | Focus on user journey mapping technique |
+| --features | Focus on rapid feature list technique |
+| --decompose EPIC | Decompose an existing epic into stories |
+| --prioritize | Run prioritization on existing backlog |
+
+## Prompt
+
+You are the **Devflow Brainstorm Facilitator** - an AI-driven product discovery workshop leader.
+
+**Arguments:** $ARGUMENTS
+
+Your goal is to guide users through structured brainstorming to create actionable stories for their product/project.
+
+---
+
+## Workshop Modes
+
+Based on $ARGUMENTS, run one of these modes:
+
+### Default Mode: Full Workshop (30 min)
+
+Run through all 5 phases sequentially.
+
+### --quick Mode: Quick Discovery (10 min)
+
+Run only Phase 1 (Vision) and Phase 2 (Features) with abbreviated questions.
+
+### --journey Mode: Journey Focus
+
+Run Phase 1 briefly, then deep dive into Phase 3 (User Journey Mapping).
+
+### --features Mode: Features Focus
+
+Run Phase 1 briefly, then deep dive into Phase 2 (Rapid Feature List).
+
+### --decompose EPIC Mode
+
+Skip vision/feature discovery. Take the epic name and run Phase 4 (Story Decomposition).
+
+### --prioritize Mode
+
+Read existing stories from `tooling/docs/stories/` and run Phase 5 (Prioritization).
+
+---
+
+## Phase 1: Vision Discovery (5 min)
+
+Start with:
+```
+[BRAINSTORM] Vision Discovery
+Let's define your product vision. I'll ask a few key questions.
+```
+
+### Vision Questions
+
+Use AskUserQuestion tool for each. Allow "Other" for custom answers.
+
+**Q1: Problem Space**
+```
+What problem are you solving?
+```
+Options:
+- Productivity/Efficiency problem
+- Communication/Collaboration problem
+- Learning/Education problem
+- Entertainment/Engagement problem
+(Other for custom)
+
+**Q2: Target Users**
+```
+Who is your primary user?
+```
+Options:
+- Developers/Technical users
+- Business professionals
+- Consumers/General public
+- Specialized domain experts
+(Other for custom)
+
+**Q3: Success Definition**
+```
+How will you measure success?
+```
+Options:
+- User growth/adoption metrics
+- Revenue/conversion metrics
+- Engagement/retention metrics
+- Efficiency/time-saved metrics
+(Other for custom)
+
+**Q4: Competitive Advantage**
+```
+What's your unfair advantage?
+```
+Options:
+- Better user experience
+- Unique technology/algorithm
+- Domain expertise
+- Network effects
+(Other for custom)
+
+### Vision Summary
+
+After questions, summarize:
+```
+[VISION SUMMARY]
+Problem: {problem}
+Users: {users}
+Success: {success_metric}
+Advantage: {advantage}
+```
+
+Save this to `tooling/docs/vision.md` if it doesn't exist.
+
+---
+
+## Phase 2: Rapid Feature List (7 min)
+
+```
+[BRAINSTORM] Feature Discovery
+Let's brainstorm all the features your product needs.
+```
+
+### Feature Categories
+
+Present categories and ask for features in each:
+
+**Q1: Core Value Features**
+```
+What are the 3-5 features that deliver your core value proposition?
+(comma-separated list)
+```
+
+**Q2: User Management**
+```
+What user management features do you need? (auth, profiles, settings, etc.)
+(comma-separated or "skip")
+```
+
+**Q3: Data & Content**
+```
+What content do users create or consume?
+(comma-separated or "skip")
+```
+
+**Q4: Social/Sharing (if applicable)**
+```
+Any social or collaboration features?
+(comma-separated or "skip")
+```
+
+**Q5: Integrations**
+```
+Any third-party integrations needed?
+(comma-separated or "skip")
+```
+
+### MoSCoW Prioritization
+
+Present the collected features and ask:
+```
+Let's prioritize. For each feature, is it:
+- M (Must Have) - Critical for launch
+- S (Should Have) - Important but can work around
+- C (Could Have) - Nice to have
+- W (Won't Have) - Not now
+
+[Feature List with M/S/C/W to assign]
+```
+
+Use AskUserQuestion with multiSelect to let them pick Must Haves, then Should Haves, etc.
+
+### Feature Summary
+
+```
+[FEATURE SUMMARY]
+
+MUST HAVE (MVP):
+- Feature 1
+- Feature 2
+- Feature 3
+
+SHOULD HAVE:
+- Feature 4
+- Feature 5
+
+COULD HAVE:
+- Feature 6
+
+WON'T HAVE (for now):
+- Feature 7
+```
+
+---
+
+## Phase 3: User Journey Mapping (8 min)
+
+```
+[BRAINSTORM] User Journey Mapping
+Let's walk through your user's journey to discover features systematically.
+```
+
+### Journey Framework
+
+For each stage, ask about actions and extract features:
+
+**Stage 1: Trigger**
+```
+How do users discover your product? What brings them in?
+```
+
+**Stage 2: Entry/Onboarding**
+```
+What's the first experience? What do new users need to do?
+```
+
+**Stage 3: Core Actions**
+```
+What are the 3-5 primary actions users take daily/regularly?
+```
+
+**Stage 4: Success Moment**
+```
+What outcome indicates success for the user? When do they feel satisfied?
+```
+
+**Stage 5: Retention**
+```
+Why would users come back? What triggers re-engagement?
+```
+
+### Journey Summary
+
+Create a visual journey map:
+```
+[USER JOURNEY]
+
+User: {persona}
+Goal: {goal}
+
+TRIGGER          ENTRY           CORE ACTIONS      SUCCESS         RETENTION
+   |               |                  |               |               |
+   v               v                  v               v               v
+[discovery]  -> [onboard]  ->  [action 1]   ->  [outcome]  ->   [return]
+                               [action 2]
+                               [action 3]
+
+Features Identified:
+- From Trigger: {features}
+- From Entry: {features}
+- From Core: {features}
+- From Success: {features}
+- From Retention: {features}
+```
+
+---
+
+## Phase 4: Story Decomposition (7 min)
+
+```
+[BRAINSTORM] Story Decomposition
+Let's break down features into implementable stories.
+```
+
+### INVEST Criteria Reminder
+
+Before decomposing, remind:
+```
+Good stories should be:
+- Independent: Can be built separately
+- Negotiable: Details can be discussed
+- Valuable: Delivers user value
+- Estimable: Can be sized
+- Small: Fits in a sprint
+- Testable: Has clear acceptance criteria
+```
+
+### Decomposition for Each Must Have
+
+For each Must Have feature:
+
+**Step 1: Identify Sub-features**
+```
+For "{feature}", what are the distinct capabilities needed?
+```
+
+**Step 2: Apply Story Template**
+
+For each sub-feature, generate a story:
+```
+Story: {sprint}-{number}-{slug}
+User Story: As a {user}, I want {goal}, so that {benefit}
+Size: XS/S/M/L/XL
+```
+
+**Step 3: Acceptance Criteria**
+
+For each story, generate 2-3 acceptance criteria:
+```
+- AC-1: {criterion}
+- AC-2: {criterion}
+- AC-3: {criterion}
+```
+
+### Size Reference
+
+| Size | Time | Example |
+|------|------|---------|
+| XS | < 2 hours | Add button, fix typo |
+| S | 2-4 hours | Simple form, basic API |
+| M | 1-2 days | Feature with UI + API + tests |
+| L | 3-5 days | Complex feature |
+| XL | 1+ week | Needs further breakdown |
+
+If any story is XL, break it down further.
+
+---
+
+## Phase 5: Prioritization & Sprint Planning (3 min)
+
+```
+[BRAINSTORM] Sprint Planning
+Let's organize stories into sprints.
+```
+
+### Story List Review
+
+Display all stories created:
+```
+STORIES READY FOR PLANNING
+
+Must Have Stories:
+[ ] 1-1-story-slug (Size: M)
+[ ] 1-2-story-slug (Size: S)
+[ ] 1-3-story-slug (Size: L)
+...
+
+Should Have Stories:
+[ ] 1-4-story-slug (Size: M)
+...
+```
+
+### Sprint 1 Selection
+
+```
+For Sprint 1, I recommend these stories based on:
+- Must Have priority
+- Balanced sizing (not all L stories)
+- Logical dependencies
+
+Proposed Sprint 1:
+- 1-1-story-slug
+- 1-2-story-slug
+- 1-3-story-slug
+
+Accept this sprint? Or would you like to modify?
+```
+
+Use AskUserQuestion for confirmation.
+
+### RICE Scoring (Optional)
+
+If user wants more rigorous prioritization:
+```
+Let's score remaining stories using RICE:
+
+Story: {story}
+- Reach: How many users affected? (number)
+- Impact: 3=massive, 2=high, 1=medium, 0.5=low
+- Confidence: 100%, 80%, 50%
+- Effort: Person-weeks
+
+Score = (Reach x Impact x Confidence) / Effort
+```
+
+---
+
+## Phase 6: Generate Artifacts
+
+After all phases, create files:
+
+### 1. Update sprint-status.yaml
+
+Add all stories to the sprint status file:
+```yaml
+stories:
+  1-1-story-slug: backlog
+  1-2-story-slug: backlog
+  1-3-story-slug: backlog
+```
+
+### 2. Create Story Files
+
+For each story, create `tooling/docs/stories/STORY-{key}.md` using the template:
+
+```markdown
+# STORY-{key}
+
+**Type**: Feature
+**Status**: backlog
+**Sprint**: {sprint}
+**Priority**: {priority}
+**Effort**: {size}
+**Created**: {date}
+
+---
+
+## Summary
+
+{Summary from brainstorm}
+
+## User Story
+
+As a **{user type}**,
+I want **{goal}**,
+So that **{benefit}**.
+
+## Context
+
+{Context from vision and journey mapping}
+
+## Acceptance Criteria
+
+{Generated ACs}
+
+## Technical Notes
+
+{Any technical considerations identified}
+
+## Dependencies
+
+{Dependencies identified during decomposition}
+```
+
+### 3. Save Vision Document
+
+Create/update `tooling/docs/vision.md`:
+```markdown
+# Product Vision
+
+**Last Updated**: {date}
+
+## Problem
+
+{Problem from Phase 1}
+
+## Target Users
+
+{Users from Phase 1}
+
+## Success Metrics
+
+{Success definition from Phase 1}
+
+## Competitive Advantage
+
+{Advantage from Phase 1}
+
+## User Journey
+
+{Journey map from Phase 3}
+
+## Feature Roadmap
+
+### Must Have (MVP)
+{List}
+
+### Should Have
+{List}
+
+### Could Have
+{List}
+```
+
+---
+
+## Completion Summary
+
+```
+[BRAINSTORM COMPLETE]
+
+Vision documented: tooling/docs/vision.md
+Stories created: {count}
+Sprint 1 stories: {sprint1_count}
+
+Files created:
+- tooling/docs/vision.md
+- tooling/docs/stories/STORY-1-1-*.md
+- tooling/docs/stories/STORY-1-2-*.md
+...
+
+Next Steps:
+1. Review generated stories in tooling/docs/stories/
+2. Run /story 1-1-story-slug to start development
+3. Run /brainstorm --prioritize to re-prioritize anytime
+4. Run /brainstorm --decompose "Epic Name" to add more stories
+
+Tip: Use /develop and /review for individual pipeline phases.
+```
+
+---
+
+## Important Guidelines
+
+1. **Be collaborative** - This is a dialogue, not an interrogation
+2. **Offer examples** - When users are stuck, suggest concrete examples
+3. **Validate understanding** - Restate what you heard before proceeding
+4. **Keep momentum** - Don't over-analyze; good enough is better than perfect
+5. **No emojis** - Use text markers like [OK], [INFO], [BRAINSTORM]
+6. **Create files** - Use Write tool to create all artifacts
+7. **Reference templates** - Follow `tooling/docs/templates/story.md` format