jettypod 3.0.1

package/SYSTEM-BEHAVIOR.md

@@ -0,0 +1,1241 @@
+# JettyPod System Behaviors
+
+*Auto-generated from test scenarios on 2025-11-06*
+
+## Summary
+
+- **13** features
+- **65** test scenarios
+- **312** test steps
+
+## Table of Contents
+
+- [Auto-generate production chores on external transition](#auto-generate-production-chores-on-external-transition) (1 scenarios)
+- [Git Hook Integration](#git-hook-integration) (4 scenarios)
+- [Git Hooks Integration](#git-hooks-integration) (1 scenarios)
+- [JettyPod update command](#jettypod-update-command) (5 scenarios)
+- [Mode Change Prompts](#mode-change-prompts) (1 scenarios)
+- [Refactor Mode](#refactor-mode) (5 scenarios)
+- [Terminal Logo Display](#terminal-logo-display) (4 scenarios)
+- [Bug Workflow Display](#bug-workflow-display) (2 scenarios)
+- [Work Commands - Stable Mode](#work-commands-stable-mode) (10 scenarios)
+- [Work Item Commands](#work-item-commands) (1 scenarios)
+- [Mode defaults to discovery on work item creation](#mode-defaults-to-discovery-on-work-item-creation) (14 scenarios)
+- [Work set-mode updates CLAUDE.md if item is current](#work-set-mode-updates-claude-md-if-item-is-current) (6 scenarios)
+- [Work start sets CLAUDE.md mode from work item](#work-start-sets-claude-md-mode-from-work-item) (11 scenarios)
+
+---
+
+## What JettyPod Does
+
+This documentation is derived from actual passing tests. It describes the verified behaviors of the system.
+
+### Auto-generate production chores on external transition
+
+*Related features: Auto-generate production chores on external transition*
+
+**Verified behaviors:**
+
+- **User transitions project to external with stable features**
+  When I have a project with 3 features in stable mode, the project state is "internal", I transition the project to external → the project state is set to "external" and a "Feature Production Readiness" epic is created and 3 production chores are created for each stable feature and the chores are grouped under the epic and I see a summary of created chores
+
+---
+
+### Git Hook Integration
+
+*Related features: Git Hook Integration*
+
+**Verified behaviors:**
+
+- **First commit updates status to in_progress**
+  When I have a work item with status "todo", the work item is set as current work, I make my first commit → the work item status should be "in_progress"
+
+- **Merge to main updates status to done**
+  When I have a work item with status "in_progress", the work item is set as current work, I am on a feature branch, I merge to main → the work item status should be "done"
+
+- **No current work item - hooks do nothing**
+  When no work item is set as current, I make a commit → no errors occur
+
+- **Integration - hooks work with existing work commands**
+  When I have initialized jettypod with git, I create a work item via work commands, I start work on the item, I commit changes → the work item status updates automatically and the current work file still exists
+
+---
+
+### Git Hooks Integration
+
+*Related features: Git Hooks Integration*
+
+**Verified behaviors:**
+
+- **Integration - post-commit hook updates status**
+  When I initialize a git repo with devpod, I create and start work on a todo item, I make a commit → the hook updates status to in_progress
+
+---
+
+### JettyPod update command
+
+*Related features: JettyPod update command*
+
+**Verified behaviors:**
+
+- **User runs jettypod update when new version is available**
+  When jettypod version 3.0.0 is installed, npm registry has version 3.1.0 available, I run update command "jettypod update" → jettypod checks npm registry for latest version and jettypod shows "New version available: 3.1.0 (current: 3.0.0)" and jettypod downloads and installs version 3.1.0 and skills are refreshed in current project and jettypod shows "✅ JettyPod updated to 3.1.0"
+
+- **User runs jettypod update when already on latest version**
+  When jettypod version 3.1.0 is installed, npm registry has version 3.1.0 available, I run update command "jettypod update" → jettypod checks npm registry for latest version and jettypod shows "Already on latest version: 3.1.0" and skills are refreshed in current project
+
+- **User runs jettypod update without internet connection**
+  When jettypod is installed, there is no internet connection, I run update command "jettypod update" → jettypod shows "Cannot check for updates: network error" and skills are still refreshed in current project using existing jettypod
+
+- **Command rename - jettypod without init creates new project**
+  When I am in a directory without .claude/, I run update command "jettypod" → jettypod initializes the project and .claude/ directory is created and CLAUDE.md is created and skills are installed
+
+- **Backwards compatibility - jettypod init still works**
+  When I am in a directory without .claude/, I run update command "jettypod init" → jettypod initializes the project and .claude/ directory is created and CLAUDE.md is created and skills are installed
+
+---
+
+### Mode Change Prompts
+
+*Related features: Mode Change Prompts*
+
+**Verified behaviors:**
+
+- **Integration - mode change with work item present**
+  When I have jettypod with a work item in progress, I check current work exists → the work item has a status
+
+---
+
+### Refactor Mode
+
+*Related features: Refactor Mode*
+
+**Verified behaviors:**
+
+- **Refactor mode integrates with work tracking**
+  When I have existing work items in the system, I enter refactor mode and audit the codebase and I select "Architectural" category and I approve creating chores for storage pattern → refactor chores are created under an epic and the epic is linked to the refactor mode work item
+
+- **User enters refactor mode and sees audit menu**
+  When I'm in a project with technical debt, I enter refactor mode → Claude audits the codebase and I see categorized menu with counts:
+
+- **User picks category and sees detailed breakdown**
+  When I see the audit menu, I pick "Architectural" category → I see detailed items with:
+
+- **Claude recommends quick wins**
+  When I see the detailed breakdown for "Architectural", Claude analyzes impact vs time → I see recommendation: "Start with Storage Pattern (quick win, high impact)" and I see warning: "Skip State Management (needs Discovery Mode first)"
+
+- **User approves and chores are created**
+  When I see recommendations for Storage Pattern, I say "create chores" → epic "Refactor: Architectural patterns" is created and chore "Create shared storage util" is created and chore "Migrate auth to storage util" is created and all chores are linked to the epic
+
+---
+
+### Terminal Logo Display
+
+*Related features: Terminal Logo Display*
+
+**Verified behaviors:**
+
+- **jettypod init displays unicode gradient logo**
+  When a new empty directory, I run jettypod init → the output contains the unicode gradient logo and the logo includes "DEV" and "POD" text and the logo uses ANSI color codes
+
+- **Logo module exports showLogo function**
+  When the logo module exists, I import it → it exports a "showLogo" function
+
+- **Logo output is properly formatted**
+  I call the showLogo function → it outputs 6 lines of logo art and it includes the version subtitle
+
+- **jettypod init integrates with existing features**
+  When a new empty directory, I run jettypod init → I see the unicode logo and the .jettypod directory is created and CLAUDE.md is created and git hooks are installed
+
+---
+
+### Bug Workflow Display
+
+*Related features: Bug Workflow Display*
+
+**Verified behaviors:**
+
+- **Starting work on a bug displays workflow guidance**
+  When jettypod is initialized, I create a bug "Install script fails", I start work on the bug → the output contains "BUG FIXING WORKFLOW" and the output contains "1. REPRODUCE" and the output contains "2. INVESTIGATE" and the output contains "3. ISOLATE" and the output contains "4. FIX" and the output contains "5. VERIFY" and the output contains "6. COMMIT"
+
+- **Starting work on a feature does not display bug workflow**
+  When jettypod is initialized, I create a feature "Add new feature", I start work on the feature → the output does not contain "BUG FIXING WORKFLOW"
+
+---
+
+### Work
+
+*Related features: Work Commands - Stable Mode*
+
+**Verified behaviors:**
+
+- **Start work with invalid ID**
+  When jettypod is initialized, I try to start work with ID "invalid" → I get an error "Invalid work item ID"
+
+- **Start work with negative ID**
+  When jettypod is initialized, I try to start work with ID "-1" → I get an error "Invalid work item ID"
+
+- **Start work when not initialized**
+  When jettypod is not initialized, I try to start work with ID "1" → I get an error "JettyPod not initialized"
+
+- **Start work on non-existent item**
+  When jettypod is initialized, I try to start work with ID "999" → I get an error "Work item #999 not found"
+
+- **Stop work with invalid status**
+  When I have current work, I try to stop work with status "invalid" → I get an error "Invalid status"
+
+- **Stop work when no current work**
+  When jettypod is initialized, no work is active, I try to stop work → operation succeeds with no changes
+
+- **Get current work with corrupted file**
+  When jettypod is initialized, current work file is corrupted, I get current work → it returns null
+
+- **Start work without git repo**
+  When jettypod is initialized without git, I have a work item, I start work on the item → it succeeds without creating branch
+
+- **Multiple start work calls**
+  When I have a work item, I start work on it, I start work on a different item → the first item stops being current and the second item becomes current
+
+- **Start work preserves existing status**
+  When I have a work item with status "in_progress", I start work on it → the status remains "in_progress"
+
+---
+
+### Work Item
+
+*Related features: Work Item Commands*
+
+**Verified behaviors:**
+
+- **Integration - work commands with existing work tracking**
+  When I have initialized jettypod, I create an epic with id 1, I create a feature with id 2 under epic 1, I start work on item 2 → the current work file exists and the current work contains item 2 and item 2 status is in_progress or backlog
+
+---
+
+### Mode defaults to discovery on work item creation
+
+*Related features: Mode defaults to discovery on work item creation*
+
+**Verified behaviors:**
+
+- **Create epic without mode**
+  When jettypod is initialized, I create an epic "Test Epic" without mode → the work item is created successfully and the work item has NULL mode
+
+- **Create epic with mode (optional)**
+  When jettypod is initialized, I create an epic "Test Epic" with mode "stable" → the work item is created successfully and the work item has mode "stable"
+
+- **Create feature with explicit mode**
+  When jettypod is initialized, I create a feature "Test Feature" with mode "speed" → the work item is created successfully and the work item has mode "speed"
+
+- **Create feature without mode defaults to discovery**
+  When jettypod is initialized, I create a feature "Test Feature" without mode → the work item is created successfully and the work item has mode "discovery"
+
+- **Create feature with invalid mode**
+  When jettypod is initialized, I try to create a feature "Test Feature" with mode "invalid" → I get an error "Invalid mode" and no work item is created
+
+- **Create bug with explicit mode**
+  When jettypod is initialized, I create a bug "Test Bug" with mode "stable" → the work item is created successfully and the work item has mode "stable"
+
+- **Create bug without mode defaults to discovery**
+  When jettypod is initialized, I create a bug "Test Bug" without mode → the work item is created successfully and the work item has mode "discovery"
+
+- **Create chore with mode fails**
+  When jettypod is initialized, I try to create a chore "Test Chore" with mode "production" → I get an error "Chores do not have modes" and no work item is created
+
+- **Create chore without mode succeeds with NULL**
+  When jettypod is initialized, jettypod is initialized, I create a chore "Test Chore" without mode and I create a feature "Test Feature" with mode "<mode>" → the work item is created successfully and the work item has NULL mode and the work item is created successfully and the work item has mode "<mode>"
+
+- **Epic with children in different modes**
+  When jettypod is initialized, I create an epic "Test Epic" without mode, I create a feature "Speed Feature" with mode "speed" and parent epic, I create a bug "Stable Bug" with mode "stable" and parent epic, I create a chore "Test Chore" without mode and parent epic, I view the work tree → I see the epic without mode indicator and I see the feature with mode "speed" and I see the bug with mode "stable" and I see the chore without mode indicator
+
+- **Create multiple items with same title but different modes**
+  When jettypod is initialized, I create a feature "Duplicate" with mode "speed" and I create a feature "Duplicate" with mode "stable" → both work items are created successfully and they have different modes
+
+- **Mode is case-sensitive**
+  When jettypod is initialized, I try to create a feature "Test" with mode "Speed" → I get an error "Invalid mode"
+
+- **Mode with whitespace is invalid**
+  When jettypod is initialized, I try to create a feature "Test" with mode " speed " → I get an error "Invalid mode"
+
+- **Empty string mode is treated as NULL**
+  When jettypod is initialized, I try to create a feature "Test" with mode "" → I get an error "Invalid mode"
+
+---
+
+### Work set-mode updates CLAUDE.md if item is current
+
+*Related features: Work set-mode updates CLAUDE.md if item is current*
+
+**Verified behaviors:**
+
+- **Set mode on current work item updates CLAUDE.md**
+  When I create a feature "Test Feature" with mode "speed", I start work on the feature, CLAUDE.md mode is set to "speed", I set mode for current item to "stable" → the work item has mode "stable" and CLAUDE.md mode is set to "stable"
+
+- **Set mode on non-current item does not update CLAUDE.md**
+  When I create a feature "Item 1" with mode "speed", I create a feature "Item 2" with mode "discovery", I start work on the feature "Item 1", CLAUDE.md mode is set to "speed", I set mode for item "Item 2" to "stable" → item "Item 2" has mode "stable"
+
+- **Set invalid mode shows error**
+  When I create a feature "Test Feature" with mode "speed", I try to set mode to "invalid" → I get error "Invalid mode" and the work item still has mode "speed"
+
+- **Set mode is case-sensitive**
+  When I create a feature "Test Feature" with mode "speed", I create a feature "Test Feature" with mode "speed", I try to set mode to "Speed" and I set mode for current item to "<new_mode>" → I get error "Invalid mode" and I start work on the feature and the work item has mode "<new_mode>" and CLAUDE.md mode is set to "<new_mode>"
+
+- **Mode change persists across work start/stop**
+  When I create a feature "Test Feature" with mode "speed", I start work on the feature, I set mode for current item to "production" and I stop work and I start work on the feature → CLAUDE.md mode is set to "production"
+
+- **Change mode multiple times**
+  When I create a feature "Test Feature" with mode "speed", I start work on the feature, I set mode for current item to "discovery" and I set mode for current item to "stable" and I set mode for current item to "production" → the work item has mode "production" and CLAUDE.md mode is set to "production"
+
+---
+
+### Work start sets CLAUDE.md mode from work item
+
+*Related features: Work start sets CLAUDE.md mode from work item*
+
+**Verified behaviors:**
+
+- **Start work on feature in speed mode**
+  When I create a feature "Speed Feature" with mode "speed", I start work on the feature → CLAUDE.md mode is set to "speed"
+
+- **Start work on bug in stable mode**
+  When I create a bug "Stable Bug" with mode "stable", I start work on the bug → CLAUDE.md mode is set to "stable"
+
+- **Start work on chore inherits parent feature mode**
+  When I create a feature "Discovery Feature" with mode "discovery", I create a chore "Child Chore" without mode and parent feature, I start work on the chore → CLAUDE.md mode is set to "discovery"
+
+- **Start work on feature in production mode**
+  When I create a feature "Production Feature" with mode "production", I start work on the feature → CLAUDE.md mode is set to "production"
+
+- **Switch from speed mode item to stable mode item**
+  When I create a feature "Speed Feature" with mode "speed", I create a bug "Stable Bug" with mode "stable", I start work on the feature, CLAUDE.md mode is set to "speed", I stop work and I start work on the bug → CLAUDE.md mode is set to "stable"
+
+- **Start work updates mode even if item already in progress**
+  When I create a feature "Test Feature" with mode "discovery", the feature status is "in_progress", CLAUDE.md has mode "speed", I start work on the feature → CLAUDE.md mode is set to "discovery"
+
+- **Start work on epic (NULL mode)**
+  When I create an epic "Test Epic" without mode, I start work on the epic → CLAUDE.md has no mode line and the current work section exists
+
+- **Start work on feature with default discovery mode**
+  When I create a feature "Default Feature" without mode, the work item has mode "discovery", I start work on the feature → CLAUDE.md mode is set to "discovery"
+
+- **Start work on child item inherits its own mode, not parent's**
+  When I create an epic "Test Epic" without mode, I create a feature "Speed Feature" with mode "speed" and parent epic, I create a bug "Stable Bug" with mode "stable" and parent epic, I start work on the speed feature and I stop work → CLAUDE.md mode is set to "speed" and I start work on the stable bug and CLAUDE.md mode is set to "stable"
+
+- **Work item mode persists in database after start**
+  When I create a feature "Test Feature" with mode "stable", I start work on the feature and I stop work → the work item still has mode "stable"
+
+- **Starting work multiple times preserves mode**
+  When I create a feature "Test Feature" with mode "production", I start work on the feature and I stop work and I start work on the feature → CLAUDE.md mode is set to "production" and the work item still has mode "production"
+
+---
+
+## Detailed Feature Specifications
+
+### Auto-generate production chores on external transition
+
+When transitioning to external, automatically create production chores for all stable features Approach: Silent Auto-Generation
+
+#### User transitions project to external with stable features
+
+**Context:**
+- I have a project with 3 features in stable mode
+- the project state is "internal"
+
+**Action:**
+- I transition the project to external
+
+**Expected outcome:**
+- the project state is set to "external"
+- a "Feature Production Readiness" epic is created
+- 3 production chores are created for each stable feature
+- the chores are grouped under the epic
+- I see a summary of created chores
+
+---
+
+### Git Hook Integration
+
+As a developer I want work item status to update automatically on git operations So that I don't have to manually track progress
+
+#### First commit updates status to in_progress
+
+**Context:**
+- I have a work item with status "todo"
+- the work item is set as current work
+
+**Action:**
+- I make my first commit
+
+**Expected outcome:**
+- the work item status should be "in_progress"
+
+#### Merge to main updates status to done
+
+**Context:**
+- I have a work item with status "in_progress"
+- the work item is set as current work
+- I am on a feature branch
+
+**Action:**
+- I merge to main
+
+**Expected outcome:**
+- the work item status should be "done"
+
+#### No current work item - hooks do nothing
+
+**Context:**
+- no work item is set as current
+
+**Action:**
+- I make a commit
+
+**Expected outcome:**
+- no errors occur
+
+#### Integration - hooks work with existing work commands
+
+**Context:**
+- I have initialized jettypod with git
+- I create a work item via work commands
+- I start work on the item
+
+**Action:**
+- I commit changes
+
+**Expected outcome:**
+- the work item status updates automatically
+- the current work file still exists
+
+---
+
+### Git Hooks Integration
+
+As a developer I want work item status to auto-update on commits So I don't manually track progress
+
+#### Integration - post-commit hook updates status
+
+**Context:**
+- I initialize a git repo with devpod
+- I create and start work on a todo item
+
+**Action:**
+- I make a commit
+
+**Expected outcome:**
+- the hook updates status to in_progress
+
+---
+
+### JettyPod update command
+
+Self-updating jettypod and skills refresh with a single command Epic: JettyPod and Skills Auto-Update Approach: Full self-update - Check npm, update jettypod, refresh skills
+
+#### User runs jettypod update when new version is available
+
+**Context:**
+- jettypod version 3.0.0 is installed
+- npm registry has version 3.1.0 available
+
+**Action:**
+- I run update command "jettypod update"
+
+**Expected outcome:**
+- jettypod checks npm registry for latest version
+- jettypod shows "New version available: 3.1.0 (current: 3.0.0)"
+- jettypod downloads and installs version 3.1.0
+- skills are refreshed in current project
+- jettypod shows "✅ JettyPod updated to 3.1.0"
+
+#### User runs jettypod update when already on latest version
+
+**Context:**
+- jettypod version 3.1.0 is installed
+- npm registry has version 3.1.0 available
+
+**Action:**
+- I run update command "jettypod update"
+
+**Expected outcome:**
+- jettypod checks npm registry for latest version
+- jettypod shows "Already on latest version: 3.1.0"
+- skills are refreshed in current project
+
+#### User runs jettypod update without internet connection
+
+**Context:**
+- jettypod is installed
+- there is no internet connection
+
+**Action:**
+- I run update command "jettypod update"
+
+**Expected outcome:**
+- jettypod shows "Cannot check for updates: network error"
+- skills are still refreshed in current project using existing jettypod
+
+#### Command rename - jettypod without init creates new project
+
+**Context:**
+- I am in a directory without .claude/
+
+**Action:**
+- I run update command "jettypod"
+
+**Expected outcome:**
+- jettypod initializes the project
+- .claude/ directory is created
+- CLAUDE.md is created
+- skills are installed
+
+#### Backwards compatibility - jettypod init still works
+
+**Context:**
+- I am in a directory without .claude/
+
+**Action:**
+- I run update command "jettypod init"
+
+**Expected outcome:**
+- jettypod initializes the project
+- .claude/ directory is created
+- CLAUDE.md is created
+- skills are installed
+
+---
+
+### Mode Change Prompts
+
+As a developer I want to update work status when switching modes So my work state stays current
+
+#### Integration - mode change with work item present
+
+**Context:**
+- I have jettypod with a work item in progress
+
+**Action:**
+- I check current work exists
+
+**Expected outcome:**
+- the work item has a status
+
+---
+
+### Refactor Mode
+
+As a developer I want an interactive audit menu for refactoring So that I can systematically clean up technical debt
+
+#### Refactor mode integrates with work tracking
+
+**Context:**
+- I have existing work items in the system
+
+**Action:**
+- I enter refactor mode and audit the codebase
+- I select "Architectural" category
+- I approve creating chores for storage pattern
+
+**Expected outcome:**
+- refactor chores are created under an epic
+- the epic is linked to the refactor mode work item
+
+#### User enters refactor mode and sees audit menu
+
+**Context:**
+- I'm in a project with technical debt
+
+**Action:**
+- I enter refactor mode
+
+**Expected outcome:**
+- Claude audits the codebase
+- I see categorized menu with counts:
+
+#### User picks category and sees detailed breakdown
+
+**Context:**
+- I see the audit menu
+
+**Action:**
+- I pick "Architectural" category
+
+**Expected outcome:**
+- I see detailed items with:
+
+#### Claude recommends quick wins
+
+**Context:**
+- I see the detailed breakdown for "Architectural"
+
+**Action:**
+- Claude analyzes impact vs time
+
+**Expected outcome:**
+- I see recommendation: "Start with Storage Pattern (quick win, high impact)"
+- I see warning: "Skip State Management (needs Discovery Mode first)"
+
+#### User approves and chores are created
+
+**Context:**
+- I see recommendations for Storage Pattern
+
+**Action:**
+- I say "create chores"
+
+**Expected outcome:**
+- epic "Refactor: Architectural patterns" is created
+- chore "Create shared storage util" is created
+- chore "Migrate auth to storage util" is created
+- all chores are linked to the epic
+
+---
+
+### Terminal Logo Display
+
+As a JettyPod user I want to see a welcoming logo when I run jettypod init So that the tool feels approachable and modern
+
+#### jettypod init displays unicode gradient logo
+
+**Context:**
+- a new empty directory
+
+**Action:**
+- I run jettypod init
+
+**Expected outcome:**
+- the output contains the unicode gradient logo
+- the logo includes "DEV" and "POD" text
+- the logo uses ANSI color codes
+
+#### Logo module exports showLogo function
+
+**Context:**
+- the logo module exists
+
+**Action:**
+- I import it
+
+**Expected outcome:**
+- it exports a "showLogo" function
+
+#### Logo output is properly formatted
+
+**Action:**
+- I call the showLogo function
+
+**Expected outcome:**
+- it outputs 6 lines of logo art
+- it includes the version subtitle
+
+#### jettypod init integrates with existing features
+
+**Context:**
+- a new empty directory
+
+**Action:**
+- I run jettypod init
+
+**Expected outcome:**
+- I see the unicode logo
+- the .jettypod directory is created
+- CLAUDE.md is created
+- git hooks are installed
+
+---
+
+### Bug Workflow Display
+
+As a developer I want to see bug-specific workflow guidance when starting a bug So that I have systematic steps to follow for fixing bugs
+
+#### Starting work on a bug displays workflow guidance
+
+**Context:**
+- jettypod is initialized
+- I create a bug "Install script fails"
+
+**Action:**
+- I start work on the bug
+
+**Expected outcome:**
+- the output contains "BUG FIXING WORKFLOW"
+- the output contains "1. REPRODUCE"
+- the output contains "2. INVESTIGATE"
+- the output contains "3. ISOLATE"
+- the output contains "4. FIX"
+- the output contains "5. VERIFY"
+- the output contains "6. COMMIT"
+
+#### Starting work on a feature does not display bug workflow
+
+**Context:**
+- jettypod is initialized
+- I create a feature "Add new feature"
+
+**Action:**
+- I start work on the feature
+
+**Expected outcome:**
+- the output does not contain "BUG FIXING WORKFLOW"
+
+---
+
+### Work Commands - Stable Mode
+
+Edge cases and error handling for work commands
+
+#### Start work with invalid ID
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to start work with ID "invalid"
+
+**Expected outcome:**
+- I get an error "Invalid work item ID"
+
+#### Start work with negative ID
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to start work with ID "-1"
+
+**Expected outcome:**
+- I get an error "Invalid work item ID"
+
+#### Start work when not initialized
+
+**Context:**
+- jettypod is not initialized
+
+**Action:**
+- I try to start work with ID "1"
+
+**Expected outcome:**
+- I get an error "JettyPod not initialized"
+
+#### Start work on non-existent item
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to start work with ID "999"
+
+**Expected outcome:**
+- I get an error "Work item #999 not found"
+
+#### Stop work with invalid status
+
+**Context:**
+- I have current work
+
+**Action:**
+- I try to stop work with status "invalid"
+
+**Expected outcome:**
+- I get an error "Invalid status"
+
+#### Stop work when no current work
+
+**Context:**
+- jettypod is initialized
+- no work is active
+
+**Action:**
+- I try to stop work
+
+**Expected outcome:**
+- operation succeeds with no changes
+
+#### Get current work with corrupted file
+
+**Context:**
+- jettypod is initialized
+- current work file is corrupted
+
+**Action:**
+- I get current work
+
+**Expected outcome:**
+- it returns null
+
+#### Start work without git repo
+
+**Context:**
+- jettypod is initialized without git
+- I have a work item
+
+**Action:**
+- I start work on the item
+
+**Expected outcome:**
+- it succeeds without creating branch
+
+#### Multiple start work calls
+
+**Context:**
+- I have a work item
+- I start work on it
+
+**Action:**
+- I start work on a different item
+
+**Expected outcome:**
+- the first item stops being current
+- the second item becomes current
+
+#### Start work preserves existing status
+
+**Context:**
+- I have a work item with status "in_progress"
+
+**Action:**
+- I start work on it
+
+**Expected outcome:**
+- the status remains "in_progress"
+
+---
+
+### Work Item Commands
+
+As a developer I want to start and stop work on items So that my current work is tracked automatically
+
+#### Integration - work commands with existing work tracking
+
+**Context:**
+- I have initialized jettypod
+- I create an epic with id 1
+- I create a feature with id 2 under epic 1
+
+**Action:**
+- I start work on item 2
+
+**Expected outcome:**
+- the current work file exists
+- the current work contains item 2
+- item 2 status is in_progress or backlog
+
+---
+
+### Mode defaults to discovery on work item creation
+
+As a developer I want new work items to default to discovery mode So I can start exploring without specifying mode every time
+
+#### Create epic without mode
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I create an epic "Test Epic" without mode
+
+**Expected outcome:**
+- the work item is created successfully
+- the work item has NULL mode
+
+#### Create epic with mode (optional)
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I create an epic "Test Epic" with mode "stable"
+
+**Expected outcome:**
+- the work item is created successfully
+- the work item has mode "stable"
+
+#### Create feature with explicit mode
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I create a feature "Test Feature" with mode "speed"
+
+**Expected outcome:**
+- the work item is created successfully
+- the work item has mode "speed"
+
+#### Create feature without mode defaults to discovery
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I create a feature "Test Feature" without mode
+
+**Expected outcome:**
+- the work item is created successfully
+- the work item has mode "discovery"
+
+#### Create feature with invalid mode
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to create a feature "Test Feature" with mode "invalid"
+
+**Expected outcome:**
+- I get an error "Invalid mode"
+- no work item is created
+
+#### Create bug with explicit mode
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I create a bug "Test Bug" with mode "stable"
+
+**Expected outcome:**
+- the work item is created successfully
+- the work item has mode "stable"
+
+#### Create bug without mode defaults to discovery
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I create a bug "Test Bug" without mode
+
+**Expected outcome:**
+- the work item is created successfully
+- the work item has mode "discovery"
+
+#### Create chore with mode fails
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to create a chore "Test Chore" with mode "production"
+
+**Expected outcome:**
+- I get an error "Chores do not have modes"
+- no work item is created
+
+#### Create chore without mode succeeds with NULL
+
+**Context:**
+- jettypod is initialized
+- jettypod is initialized
+
+**Action:**
+- I create a chore "Test Chore" without mode
+- I create a feature "Test Feature" with mode "<mode>"
+
+**Expected outcome:**
+- the work item is created successfully
+- the work item has NULL mode
+- the work item is created successfully
+- the work item has mode "<mode>"
+
+#### Epic with children in different modes
+
+**Context:**
+- jettypod is initialized
+- I create an epic "Test Epic" without mode
+- I create a feature "Speed Feature" with mode "speed" and parent epic
+- I create a bug "Stable Bug" with mode "stable" and parent epic
+- I create a chore "Test Chore" without mode and parent epic
+
+**Action:**
+- I view the work tree
+
+**Expected outcome:**
+- I see the epic without mode indicator
+- I see the feature with mode "speed"
+- I see the bug with mode "stable"
+- I see the chore without mode indicator
+
+#### Create multiple items with same title but different modes
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I create a feature "Duplicate" with mode "speed"
+- I create a feature "Duplicate" with mode "stable"
+
+**Expected outcome:**
+- both work items are created successfully
+- they have different modes
+
+#### Mode is case-sensitive
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to create a feature "Test" with mode "Speed"
+
+**Expected outcome:**
+- I get an error "Invalid mode"
+
+#### Mode with whitespace is invalid
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to create a feature "Test" with mode " speed "
+
+**Expected outcome:**
+- I get an error "Invalid mode"
+
+#### Empty string mode is treated as NULL
+
+**Context:**
+- jettypod is initialized
+
+**Action:**
+- I try to create a feature "Test" with mode ""
+
+**Expected outcome:**
+- I get an error "Invalid mode"
+
+---
+
+### Work set-mode updates CLAUDE.md if item is current
+
+As a developer I want to change a work item's mode with jettypod work set-mode So I can adjust my approach without recreating the work item Given jettypod is initialized And CLAUDE.md exists
+
+#### Set mode on current work item updates CLAUDE.md
+
+**Context:**
+- I create a feature "Test Feature" with mode "speed"
+- I start work on the feature
+- CLAUDE.md mode is set to "speed"
+
+**Action:**
+- I set mode for current item to "stable"
+
+**Expected outcome:**
+- the work item has mode "stable"
+- CLAUDE.md mode is set to "stable"
+
+#### Set mode on non-current item does not update CLAUDE.md
+
+**Context:**
+- I create a feature "Item 1" with mode "speed"
+- I create a feature "Item 2" with mode "discovery"
+- I start work on the feature "Item 1"
+- CLAUDE.md mode is set to "speed"
+
+**Action:**
+- I set mode for item "Item 2" to "stable"
+
+**Expected outcome:**
+- item "Item 2" has mode "stable"
+
+#### Set invalid mode shows error
+
+**Context:**
+- I create a feature "Test Feature" with mode "speed"
+
+**Action:**
+- I try to set mode to "invalid"
+
+**Expected outcome:**
+- I get error "Invalid mode"
+- the work item still has mode "speed"
+
+#### Set mode is case-sensitive
+
+**Context:**
+- I create a feature "Test Feature" with mode "speed"
+- I create a feature "Test Feature" with mode "speed"
+
+**Action:**
+- I try to set mode to "Speed"
+- I set mode for current item to "<new_mode>"
+
+**Expected outcome:**
+- I get error "Invalid mode"
+- I start work on the feature
+- the work item has mode "<new_mode>"
+- CLAUDE.md mode is set to "<new_mode>"
+
+#### Mode change persists across work start/stop
+
+**Context:**
+- I create a feature "Test Feature" with mode "speed"
+- I start work on the feature
+
+**Action:**
+- I set mode for current item to "production"
+- I stop work
+- I start work on the feature
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "production"
+
+#### Change mode multiple times
+
+**Context:**
+- I create a feature "Test Feature" with mode "speed"
+- I start work on the feature
+
+**Action:**
+- I set mode for current item to "discovery"
+- I set mode for current item to "stable"
+- I set mode for current item to "production"
+
+**Expected outcome:**
+- the work item has mode "production"
+- CLAUDE.md mode is set to "production"
+
+---
+
+### Work start sets CLAUDE.md mode from work item
+
+As a developer I want jettypod work start to set the CLAUDE.md mode from the work item's mode So I automatically work in the correct mode for each work item Given jettypod is initialized And CLAUDE.md exists
+
+#### Start work on feature in speed mode
+
+**Context:**
+- I create a feature "Speed Feature" with mode "speed"
+
+**Action:**
+- I start work on the feature
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "speed"
+
+#### Start work on bug in stable mode
+
+**Context:**
+- I create a bug "Stable Bug" with mode "stable"
+
+**Action:**
+- I start work on the bug
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "stable"
+
+#### Start work on chore inherits parent feature mode
+
+**Context:**
+- I create a feature "Discovery Feature" with mode "discovery"
+- I create a chore "Child Chore" without mode and parent feature
+
+**Action:**
+- I start work on the chore
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "discovery"
+
+#### Start work on feature in production mode
+
+**Context:**
+- I create a feature "Production Feature" with mode "production"
+
+**Action:**
+- I start work on the feature
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "production"
+
+#### Switch from speed mode item to stable mode item
+
+**Context:**
+- I create a feature "Speed Feature" with mode "speed"
+- I create a bug "Stable Bug" with mode "stable"
+- I start work on the feature
+- CLAUDE.md mode is set to "speed"
+
+**Action:**
+- I stop work
+- I start work on the bug
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "stable"
+
+#### Start work updates mode even if item already in progress
+
+**Context:**
+- I create a feature "Test Feature" with mode "discovery"
+- the feature status is "in_progress"
+- CLAUDE.md has mode "speed"
+
+**Action:**
+- I start work on the feature
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "discovery"
+
+#### Start work on epic (NULL mode)
+
+**Context:**
+- I create an epic "Test Epic" without mode
+
+**Action:**
+- I start work on the epic
+
+**Expected outcome:**
+- CLAUDE.md has no mode line
+- the current work section exists
+
+#### Start work on feature with default discovery mode
+
+**Context:**
+- I create a feature "Default Feature" without mode
+- the work item has mode "discovery"
+
+**Action:**
+- I start work on the feature
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "discovery"
+
+#### Start work on child item inherits its own mode, not parent's
+
+**Context:**
+- I create an epic "Test Epic" without mode
+- I create a feature "Speed Feature" with mode "speed" and parent epic
+- I create a bug "Stable Bug" with mode "stable" and parent epic
+
+**Action:**
+- I start work on the speed feature
+- I stop work
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "speed"
+- I start work on the stable bug
+- CLAUDE.md mode is set to "stable"
+
+#### Work item mode persists in database after start
+
+**Context:**
+- I create a feature "Test Feature" with mode "stable"
+
+**Action:**
+- I start work on the feature
+- I stop work
+
+**Expected outcome:**
+- the work item still has mode "stable"
+
+#### Starting work multiple times preserves mode
+
+**Context:**
+- I create a feature "Test Feature" with mode "production"
+
+**Action:**
+- I start work on the feature
+- I stop work
+- I start work on the feature
+
+**Expected outcome:**
+- CLAUDE.md mode is set to "production"
+- the work item still has mode "production"
+
+---
+