@pjmendonca/devflow 1.13.2 → 1.19.0

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

package/.claude/skills/costs/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: costs
+description: View cost dashboard and spending analytics (project)
+---
+
+# Cost Dashboard Skill
+
+Display Devflow cost tracking and spending analytics by reading session data directly.
+
+## Usage
+
+```
+/costs [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| --period day | Show today's costs only |
+| --period week | Show this week's costs |
+| --period month | Show this month's costs (default) |
+| --history N | Show last N sessions |
+| --story KEY | Filter by story key |
+
+## Prompt
+
+You are displaying the Devflow cost dashboard.
+
+**Arguments:** $ARGUMENTS
+
+### Step 1: Read Configuration
+
+Read the configuration file:
+- Path: `tooling/.automation/costs/config.json`
+
+This contains:
+- `budget_dev`: Development budget (USD)
+- `subscription_plan`: Current plan (free/pro)
+- `subscription_token_limit`: Monthly token limit
+- `subscription_billing_period_days`: Days in billing period
+- `display_currencies`: Currencies to show
+- `currency_rates`: Exchange rates
+
+### Step 2: Find Session Files
+
+Find all session files:
+- Path pattern: `tooling/.automation/costs/sessions/*.json`
+
+### Step 3: Read and Aggregate Session Data
+
+For each session file, extract:
+- `session_id`: Session identifier
+- `start_time` / `end_time`: Timestamps
+- `story_key`: Associated story (if any)
+- `entries[]`: Array of cost entries with `model`, `input_tokens`, `output_tokens`, `cost_usd`
+- `totals`: Aggregated totals for the session
+
+Identify the most recent session as the "current session".
+
+### Step 4: Calculate Metrics
+
+Calculate:
+1. **Current session tokens/cost**: From the most recent session
+2. **Cumulative tokens**: Sum of all tokens across ALL sessions this billing period
+3. **Cumulative cost**: Sum of all `cost_usd` across ALL sessions
+4. **Cost by model**: Group costs by model (opus, sonnet, haiku)
+5. **Cost by story**: Group costs by story_key
+6. **Budget usage**: (cumulative_cost / budget_dev) * 100
+7. **Subscription usage**: (cumulative_tokens / subscription_token_limit) * 100
+8. **Average cost per session**: cumulative_cost / session_count
+9. **Average tokens per session**: cumulative_tokens / session_count
+10. **Input/output ratio**: total_input_tokens / total_output_tokens
+11. **Days remaining**: Calculate from billing period start
+12. **Projected monthly cost**: (cumulative_cost / days_elapsed) * 30
+13. **Projected token usage**: (cumulative_tokens / days_elapsed) * 30
+
+### Step 5: Apply Filters
+
+Based on $ARGUMENTS:
+- `--period day`: Filter sessions from today only
+- `--period week`: Filter sessions from last 7 days
+- `--period month`: Filter sessions from last 30 days (default)
+- `--history N`: Show only last N sessions
+- `--story KEY`: Filter sessions matching story_key
+
+### Step 6: Format Output
+
+Display the dashboard using this format:
+
+```
+=================================================================
+                    DEVFLOW COST DASHBOARD
+=================================================================
+Plan: [plan] | Tokens: [cumulative]/[limit] ([%]%) | [days] days left
+This Session: $[current_cost] | Cumulative: $[total_cost]
+=================================================================
+
+PERIOD: [period]                        SESSIONS: [count]
+
+--- TOKEN USAGE ---------------------------------------------
+                   This Session         Cumulative
+Input:             [current_in]         [total_in]
+Output:            [current_out]        [total_out]
+Total:             [current_total]      [total_total]
+
+I/O Ratio:         [ratio]:1 (higher = more input-heavy conversations)
+
+--- COST BY MODEL -------------------------------------------
+[model]            $[cost]  ([%]%)  [bar]
+
+--- COST BY STORY -------------------------------------------
+[story-key]        $[cost]  ([%]%)
+(no story)         $[cost]  ([%]%)
+
+--- BUDGET STATUS -------------------------------------------
+Spent:     $[total]  /  $[budget]  ([%]%)
+[================================--------------------] [%]%
+
+[WARNING] if > 75%: "Approaching budget limit!"
+[CRITICAL] if > 90%: "Near budget limit - consider pausing"
+
+--- PROJECTIONS (based on current usage rate) ---------------
+Monthly token projection:    [projected] / [limit] ([%]%)
+Monthly cost projection:     $[projected_cost]
+Avg cost per session:        $[avg_cost]
+Avg tokens per session:      [avg_tokens]
+
+--- RECENT SESSIONS -----------------------------------------
+[session_id]  [date]  [tokens]  $[cost]  [story or "-"]
+[session_id]  [date]  [tokens]  $[cost]  [story or "-"]
+[session_id]  [date]  [tokens]  $[cost]  [story or "-"]
+(show last 5 sessions)
+
+--- CURRENCIES ----------------------------------------------
+$[USD] | E[EUR] | L[GBP] | R$[BRL]
+=================================================================
+```
+
+### Budget Warnings
+
+Display warnings based on config thresholds:
+- If budget usage > `warning_percent` (75%): Show [WARNING]
+- If budget usage > `critical_percent` (90%): Show [CRITICAL]
+- If subscription usage > 80%: Show token limit warning
+
+### Notes
+
+- Format large numbers with K/M suffixes (e.g., 1.5K, 2.3M)
+- Round costs to 2 decimal places
+- Show percentages to 1 decimal place
+- Use text-based progress bars with = and - characters
+- Current session = most recent session file by timestamp
+- Cumulative = sum of ALL sessions in the billing period
+- If no sessions found, display a message indicating no cost data available
+- Calculate days remaining: billing_period_days - days since first session of period