jettypod 3.0.1

package/docs/COMMAND_REFERENCE.md

@@ -0,0 +1,903 @@
+# JettyPod Command Reference
+
+Complete reference for all JettyPod commands as of 2025-10-31.
+
+---
+
+## Table of Contents
+
+1. [Initialization & Setup](#initialization--setup)
+2. [Project Discovery](#project-discovery)
+3. [Work Item Management](#work-item-management)
+4. [Epic Discovery](#epic-discovery)
+5. [Feature Discovery](#feature-discovery)
+6. [Work Status & Navigation](#work-status--navigation)
+7. [Mode Management](#mode-management)
+8. [Decisions](#decisions)
+9. [Project State](#project-state)
+10. [Git Integration](#git-integration)
+
+---
+
+## Initialization & Setup
+
+### `jettypod init <project-name>`
+
+Initialize JettyPod in the current directory.
+
+```bash
+jettypod init "My Project"
+```
+
+**What it does:**
+- Creates `.jettypod/` directory
+- Generates `CLAUDE.md` with project context
+- Sets up database (work.db)
+- Installs git hooks (if git repository exists)
+- Installs discovery skills for Claude Code
+
+**Output:**
+```
+📝 CLAUDE.md generated
+✓ Git hooks installed
+🔒 Claude Code hook installed
+✅ JettyPod initialized
+```
+
+---
+
+## Project Discovery
+
+### `jettypod project discover start`
+
+Begin project-level discovery process.
+
+```bash
+jettypod project discover start
+```
+
+**What it does:**
+- Marks project as "in discovery" phase
+- Activates Claude Code discovery protocol
+- Prepares for UX approach exploration
+
+**Typical workflow:**
+1. User describes what users DO in the product
+2. Claude presents 3 UX approaches
+3. Optionally build prototypes
+4. User selects winning approach
+5. Complete discovery with decision
+
+---
+
+### `jettypod project discover complete`
+
+Complete project discovery with decision.
+
+```bash
+jettypod project discover complete \
+  --winner="prototypes/web-react" \
+  --rationale="Web-first for fastest time to market" \
+  --prototypes="prototypes/web-react.js,prototypes/mobile-pwa.js"
+```
+
+**Required flags:**
+- `--winner=<path>` - Path to winning prototype or approach name
+- `--rationale="<text>"` - Why this approach was chosen
+
+**Optional flags:**
+- `--prototypes="<file1>,<file2>"` - Comma-separated list of prototype files
+
+**What it does:**
+- Records project-level decision
+- Stores prototype tracking info
+- Updates DECISIONS.md
+- Marks discovery as completed
+
+---
+
+## Work Item Management
+
+### `jettypod work create epic <title> [description] [flags]`
+
+Create a new epic.
+
+```bash
+# Simple epic
+jettypod work create epic "User Authentication"
+
+# Epic with description
+jettypod work create epic "User Authentication" "Secure login system"
+
+# Epic requiring architectural discovery
+jettypod work create epic "Real-time Updates" "Live data sync" --needs-discovery
+```
+
+**Optional flags:**
+- `--needs-discovery` - Epic requires architectural decisions
+- `--mode=<mode>` - Set initial mode (discovery/speed/stable/production)
+
+**What it creates:**
+- Epic work item in database
+- Entry in work tree
+- Triggers epic discovery prompt if `--needs-discovery` flag set
+
+---
+
+### `jettypod work create feature <title> [description] [flags]`
+
+Create a new feature.
+
+```bash
+# Feature without parent
+jettypod work create feature "Login Form"
+
+# Feature with description
+jettypod work create feature "Login Form" "User login UI component"
+
+# Feature under an epic
+jettypod work create feature "Password Reset" "Forgot password flow" --parent=5
+
+# Feature with initial mode
+jettypod work create feature "Dashboard" "User dashboard" --mode=stable
+```
+
+**Optional flags:**
+- `--parent=<id>` - Parent epic ID
+- `--mode=<mode>` - Initial mode (defaults to discovery for features)
+
+**What it creates:**
+- Feature in "discovery" phase by default
+- Database entry with phase tracking
+- Prompts for feature discovery
+
+---
+
+### `jettypod work create chore <title> [description] [flags]`
+
+Create a chore (non-feature work).
+
+```bash
+jettypod work create chore "Update dependencies"
+jettypod work create chore "Refactor auth module" --parent=5
+```
+
+**Optional flags:**
+- `--parent=<id>` - Parent work item ID
+- `--mode=<mode>` - Initial mode
+
+---
+
+### `jettypod work create bug <title> [description] [flags]`
+
+Create a bug.
+
+```bash
+jettypod work create bug "Login fails on Safari"
+jettypod work create bug "Memory leak in dashboard" --parent=10
+```
+
+**Optional flags:**
+- `--parent=<id>` - Parent work item ID
+- `--mode=<mode>` - Initial mode (defaults to stable)
+
+---
+
+## Epic Discovery
+
+### `jettypod work epic-discover <epic-id>`
+
+Start architectural discovery for an epic.
+
+```bash
+jettypod work epic-discover 5
+```
+
+**Prerequisites:**
+- Epic must have `needs_discovery=1` flag
+- Epic must be in backlog/todo status
+
+**What it does:**
+- Activates epic-discover skill in Claude Code
+- Guides through architectural decision process
+- Helps identify key technical decisions needed
+
+**Typical flow:**
+1. Brainstorm features for the epic
+2. Identify architectural decisions needed
+3. Explore technical approaches (optional prototypes)
+4. Make decisions with `epic-implement`
+
+---
+
+### `jettypod work epic-implement <epic-id> [flags]`
+
+Record architectural decision for an epic.
+
+```bash
+jettypod work epic-implement 5 \
+  --aspect="Authentication" \
+  --decision="JWT with refresh tokens" \
+  --rationale="Stateless, scalable, mobile-friendly" \
+  --prototypes="prototypes/jwt.js,prototypes/session.js,prototypes/oauth.js"
+```
+
+**Required flags:**
+- `--aspect="<category>"` - Type of decision (Architecture/Database/API/etc)
+- `--decision="<approach>"` - The chosen approach
+- `--rationale="<reason>"` - Why this was chosen
+
+**Optional flags:**
+- `--prototypes="<files>"` - Comma-separated prototype file paths
+
+**What it does:**
+- Records decision in `discovery_decisions` table
+- Updates DECISIONS.md with architectural choice
+- Stores prototype tracking (files + winner)
+- Links decision to epic
+
+**Can be called multiple times** for different aspects:
+```bash
+# Authentication decision
+jettypod work epic-implement 5 \
+  --aspect="Authentication" \
+  --decision="JWT" \
+  --rationale="Stateless"
+
+# Database decision
+jettypod work epic-implement 5 \
+  --aspect="Database" \
+  --decision="PostgreSQL" \
+  --rationale="ACID guarantees needed"
+```
+
+---
+
+## Feature Discovery
+
+### `jettypod work discover <feature-id>`
+
+Start UX discovery for a feature.
+
+```bash
+jettypod work discover 12
+```
+
+**Prerequisites:**
+- Must be a feature (not epic/chore/bug)
+- Feature must be in "discovery" phase
+
+**What it does:**
+- Activates feature-discover skill
+- Guides through UX approach exploration
+- Generates BDD scenarios
+- Helps create discovery checkpoints
+
+**Typical flow:**
+1. Explore 3 UX approaches
+2. (Optional) Build throwaway prototypes
+3. Select winning approach
+4. Generate BDD scenarios
+5. Transition to implementation
+
+---
+
+### `jettypod work implement <feature-id> [flags]`
+
+Transition feature from discovery to implementation.
+
+```bash
+# Simple transition
+jettypod work implement 12
+
+# With prototype tracking
+jettypod work implement 12 \
+  --prototypes="prototypes/modal.html,prototypes/page.html" \
+  --winner="prototypes/modal.html"
+```
+
+**Optional flags:**
+- `--prototypes="<files>"` - Comma-separated prototype paths
+- `--winner="<path>"` - Winning prototype path
+
+**What it does:**
+- Changes phase from "discovery" to "implementation"
+- Sets mode to "speed" by default
+- Stores prototype tracking info
+- Displays speed mode guidance
+
+**Output:**
+```
+✅ Feature #12 transitioned to Implementation Phase
+
+Title: Login Form
+Phase: Implementation
+Mode: Speed
+Prototypes: prototypes/modal.html, prototypes/page.html
+Winner: prototypes/modal.html
+
+🚀 Speed Mode: Prove It Works
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Build code that passes happy path scenarios.
+Focus: Happy path only, single file when possible
+```
+
+---
+
+## Work Status & Navigation
+
+### `jettypod work tree [flags]`
+
+Display hierarchical tree of all work items.
+
+```bash
+# Collapsed view (default)
+jettypod work tree
+
+# Expand specific items
+jettypod work tree --expand=1
+jettypod work tree --expand=1,5,10
+
+# Expand all items
+jettypod work tree --expand-all
+```
+
+**Flags:**
+- `--expand=<ids>` - Comma-separated IDs to expand
+- `--expand-all` - Show all details
+
+**Output shows:**
+- Recently completed items at top
+- Hierarchical structure (epics → features → chores/bugs)
+- Status, mode, and phase indicators
+- Progress indicators for epics
+
+---
+
+### `jettypod work show <id>`
+
+Show detailed information for a work item.
+
+```bash
+jettypod work show 12
+```
+
+**Output includes:**
+- ID and title
+- Type and status
+- Mode (if set)
+- Phase (for features: discovery/implementation)
+- Parent and epic relationships
+- Prototype tracking (if present)
+- Discovery decisions (for epics)
+- Description
+
+**Example output:**
+```
+#12 Login Form
+Type: feature
+Status: backlog
+Mode: speed
+Phase: implementation
+Parent: #5 User Authentication
+Epic: #5 User Authentication
+
+🔬 Prototypes: prototypes/modal.html, prototypes/page.html
+✅ Winner: prototypes/modal.html
+
+Description: User login UI component
+```
+
+---
+
+### `jettypod work status <id> <status>`
+
+Update work item status.
+
+```bash
+jettypod work status 12 in_progress
+jettypod work status 12 done
+```
+
+**Valid statuses:**
+- `backlog` - Not started
+- `todo` - Ready to work
+- `in_progress` - Currently working
+- `done` - Completed
+
+**Special behaviors:**
+- Marking parent as done also completes all children
+- Marking last child as done auto-completes parent
+
+---
+
+### `jettypod work describe <id> <description>`
+
+Add or update work item description.
+
+```bash
+jettypod work describe 12 "User login form with email and password"
+```
+
+---
+
+### `jettypod work start [id]`
+
+Start work on an item (sets as current work).
+
+```bash
+# Start specific item
+jettypod work start 12
+
+# Start current work item (if one exists)
+jettypod work start
+```
+
+**What it does:**
+- Sets item as current work
+- Updates status to `in_progress` if `todo`
+- Updates CLAUDE.md with current context
+- Creates `.jettypod/current-work.json`
+
+---
+
+### `jettypod work stop`
+
+Stop current work.
+
+```bash
+jettypod work stop
+```
+
+**What it does:**
+- Clears current work
+- Removes work context from CLAUDE.md
+- Deletes `.jettypod/current-work.json`
+
+---
+
+### `jettypod work current`
+
+Show current work item.
+
+```bash
+jettypod work current
+```
+
+**Output:**
+```
+Currently working on: #12 Login Form
+Type: feature
+Status: in_progress
+```
+
+---
+
+## Mode Management
+
+### `jettypod work set-mode <id> <mode>`
+
+Change work item mode.
+
+```bash
+jettypod work set-mode 12 stable
+jettypod work set-mode 12 production
+```
+
+**Valid modes:**
+- `discovery` - Explore options, prototype
+- `speed` - Ship in 2h max, minimal testing
+- `stable` - Make it dependable, comprehensive tests
+- `production` - Build robust systems, full quality
+
+**What it does:**
+- Updates mode in database
+- Updates CLAUDE.md if this is current work
+- Displays mode-specific guidance
+
+---
+
+### `jettypod work elevate <id> <mode>`
+
+Elevate work item to higher quality mode.
+
+```bash
+# Elevate from speed to stable
+jettypod work elevate 12 stable
+
+# Elevate from stable to production
+jettypod work elevate 12 production
+```
+
+**Mode progression:**
+- discovery → speed → stable → production
+
+**What it does:**
+- Changes mode to specified level
+- Displays elevation guidance
+- Updates current work context
+
+---
+
+## Decisions
+
+### `jettypod decisions show`
+
+Show all decisions chronologically.
+
+```bash
+jettypod decisions show
+```
+
+**Displays:**
+- Project-level decisions (UX/tech stack)
+- Epic-level decisions (architectural)
+- Feature-level decisions
+- Chronological ordering
+
+---
+
+### `jettypod decisions show project`
+
+Show only project-level decisions.
+
+```bash
+jettypod decisions show project
+```
+
+**Output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 PROJECT-LEVEL DECISIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Winner: prototypes/web-react
+Rationale: Web-first for fastest time to market
+Decided: 10/29/2025
+```
+
+---
+
+### `jettypod decisions show epic <id>`
+
+Show architectural decisions for an epic.
+
+```bash
+jettypod decisions show epic 5
+```
+
+**Output:**
+```
+🏛  Discovery Decisions for Epic #5:
+
+   Authentication:
+   Decision: JWT with refresh tokens
+   Rationale: Stateless, scalable, mobile-friendly
+
+   Database:
+   Decision: PostgreSQL
+   Rationale: ACID guarantees needed
+```
+
+---
+
+### `jettypod decisions view`
+
+Open DECISIONS.md file.
+
+```bash
+jettypod decisions view
+```
+
+**What it does:**
+- Displays contents of `docs/DECISIONS.md`
+- Shows formatted decision history
+- Auto-generated from database
+
+---
+
+## Project State
+
+### `jettypod project state <state>`
+
+Set project state/environment.
+
+```bash
+jettypod project state internal
+jettypod project state external
+```
+
+**Valid states:**
+- `internal` - Team only, staging/preview, no external users
+- `external` - Public-facing, has external users
+
+**What it does:**
+- Updates project_state in config
+- Affects quality expectations
+- Influences mode guidance
+
+---
+
+### `jettypod project ready`
+
+Check external readiness status.
+
+```bash
+jettypod project ready
+```
+
+**Shows checklist of:**
+- External user preparation items
+- Security hardening
+- Compliance requirements
+- Production readiness
+
+---
+
+### `jettypod project ready check <category> <item-key>`
+
+Mark readiness item as complete.
+
+```bash
+jettypod project ready check security auth_hardening
+```
+
+---
+
+## Git Integration
+
+JettyPod automatically integrates with git through hooks:
+
+### Pre-commit Hook
+- Runs tests before allowing commit
+- Can be bypassed with `--no-verify`
+
+### Post-commit Hook
+- Updates DECISIONS.md from database
+- Auto-generates documentation
+
+### Post-merge Hook
+- Resets database connection
+- Ensures schema is current
+
+---
+
+## Command Patterns & Tips
+
+### Working with Epics
+```bash
+# 1. Create epic needing discovery
+jettypod work create epic "User Auth" "Secure login" --needs-discovery
+
+# 2. Discover architectural decisions
+jettypod work epic-discover 1
+
+# 3. Record decisions
+jettypod work epic-implement 1 \
+  --aspect="Authentication" \
+  --decision="JWT" \
+  --rationale="Stateless scaling"
+
+# 4. Create features under epic
+jettypod work create feature "Login UI" --parent=1
+```
+
+### Working with Features
+```bash
+# 1. Create feature (starts in discovery)
+jettypod work create feature "Login Form" --parent=1
+
+# 2. Explore UX approaches
+jettypod work discover 2
+
+# 3. Transition to implementation
+jettypod work implement 2 --winner="prototypes/modal.html"
+
+# 4. Build in speed mode
+jettypod work start 2
+# ... build minimal working version ...
+
+# 5. Elevate to stable
+jettypod work set-mode 2 stable
+# ... add comprehensive tests ...
+
+# 6. Mark complete
+jettypod work status 2 done
+```
+
+### Prototype Tracking Pattern
+```bash
+# Project level
+jettypod project discover complete \
+  --winner="web-app" \
+  --rationale="Mobile web for widest reach" \
+  --prototypes="proto-1.html,proto-2.html,proto-3.html"
+
+# Epic level
+jettypod work epic-implement 5 \
+  --aspect="API" \
+  --decision="GraphQL" \
+  --rationale="Flexible data fetching" \
+  --prototypes="rest-api.js,graphql-api.js,grpc.js"
+
+# Feature level
+jettypod work implement 12 \
+  --prototypes="modal.html,page.html,drawer.html" \
+  --winner="modal.html"
+```
+
+### Current Work Pattern
+```bash
+# Start work
+jettypod work start 12
+
+# Check what you're working on
+jettypod work current
+
+# Stop work
+jettypod work stop
+```
+
+---
+
+## Database Schema
+
+JettyPod uses SQLite with the following main tables:
+
+### `work_items`
+- Core work item storage
+- Tracks type, status, mode, phase
+- Hierarchical relationships (parent_id, epic_id)
+- Prototype tracking (prototype_files, discovery_winner)
+
+### `discovery_decisions`
+- Architectural decisions for epics
+- Links to work_items
+- Stores aspect, decision, rationale
+
+### `project_config`
+- Project-level settings
+- Singleton table (id=1)
+- project_state field
+
+### `external_readiness_checklist`
+- External user readiness tracking
+- Category-based organization
+
+---
+
+## File Structure
+
+```
+.jettypod/
+├── work.db              # SQLite database
+├── current-work.json    # Active work item
+├── config.json          # Project configuration
+└── skills/              # Discovery skills for Claude Code
+    ├── epic-discover/
+    └── feature-discover/
+
+docs/
+└── DECISIONS.md         # Auto-generated decision log
+
+CLAUDE.md               # Project context for Claude Code
+```
+
+---
+
+## Mode Behavior Reference
+
+| Mode | Max Time | Testing | Error Handling | Code Quality | Use Case |
+|------|----------|---------|----------------|--------------|----------|
+| **discovery** | No limit | None | None | Throwaway | Explore approaches |
+| **speed** | 2 hours | Happy path | Basic try/catch | Single file | Prove it works |
+| **stable** | No limit | Comprehensive | Full coverage | Maintainable | Dependable feature |
+| **production** | No limit | Full suite | Bulletproof | Enterprise | External users |
+
+---
+
+## Phase Behavior (Features Only)
+
+Features have two phases:
+
+### Discovery Phase
+- Explore UX approaches
+- Build throwaway prototypes
+- Generate BDD scenarios
+- Default mode: `discovery`
+- Display: `[🔍 discovery]`
+
+### Implementation Phase
+- Build production code
+- Follow chosen approach
+- Default mode: `speed`
+- Display: `[speed]`, `[stable]`, or `[production]`
+
+Transition with: `jettypod work implement <id>`
+
+---
+
+## Integration with Claude Code
+
+JettyPod is designed to work seamlessly with Claude Code:
+
+### CLAUDE.md Integration
+- Auto-updates with current work context
+- Includes mode-specific guidance
+- Shows project state and decisions
+
+### Discovery Skills
+- `epic-discover` - Guides architectural decisions
+- `feature-discover` - Guides UX exploration
+
+### Automatic Triggers
+- Creating epic with `--needs-discovery` → prompts epic-discover
+- Creating feature → prompts feature-discover
+- Starting work → updates Claude context
+
+---
+
+## Best Practices
+
+1. **Start with Project Discovery**
+   - Understand user journey first
+   - Explore 3 UX approaches
+   - Build prototypes to validate
+
+2. **Epic Discovery for Architecture**
+   - Use `--needs-discovery` flag
+   - Make decisions before creating features
+   - Track prototypes for future reference
+
+3. **Feature Discovery for UX**
+   - Every feature starts in discovery phase
+   - Explore approaches before building
+   - Transition consciously to implementation
+
+4. **Mode Progression**
+   - Start in speed mode (2h max)
+   - Elevate to stable (comprehensive tests)
+   - Only use production for external users
+
+5. **Track Prototypes**
+   - Use `--prototypes` flags consistently
+   - Mark winners with `--winner`
+   - Reference in future decisions
+
+6. **Use Work Tree**
+   - `jettypod work tree` for overview
+   - `--expand` to see details
+   - Track progress visually
+
+---
+
+## Troubleshooting
+
+### "Work item #NaN not found"
+Use: `jettypod work show <id>` (ID is required)
+
+### "Epic does not need discovery"
+Add flag when creating: `--needs-discovery`
+
+### "Feature not in discovery phase"
+Check phase with `jettypod work show <id>`
+
+### Database locked
+Close other JettyPod instances or wait for background operations
+
+### Git hooks failing tests
+Use `--no-verify` flag: `git commit --no-verify -m "message"`
+
+---
+
+## Version
+
+This reference is current as of JettyPod v3.0.0 (2025-10-31)
+
+Features included:
+- Multi-level prototype tracking
+- Feature phase tracking (discovery/implementation)
+- Decision tracking and DECISIONS.md generation
+- Epic and feature discovery skills
+- Mode management system
+- Project state management