# Bangstack CLI Workflow

## The Complete Development Flow

### Step 1: Create Requirements File

```bash
# Create your requirements in plain English
vim requirements.md
```

```markdown
# E-commerce Store Requirements

## User Journeys
### Customer Checkout Flow
1. Customer browses products
2. Customer adds items to cart
3. Customer checks out with PayPal, Klarna, or Credit Card
4. Customer receives confirmation email
...
```

### Step 2: Analyze Requirements

```bash
$ bang analyze requirements.md

Analyzing requirements...

✓ Found 2 user journeys:
  - Customer Checkout Flow (10 steps)
  - Admin Order Management (4 steps)

✓ Identified 6 components:
  - catalog
  - cart
  - checkout
  - order_management
  - email_system
  - analytics

✓ Identified 8 events:
  - product_viewed
  - product_added_to_cart
  - cart_viewed
  - payment_method_selected
  - payment_completed
  - order_created
  - order_status_changed
  - email_sent

✓ Detected 3 payment integrations:
  - PayPal
  - Klarna
  - Stripe

I have a few questions to clarify:

1. Should customers be able to checkout as guests, or must they create an account?
2. For the cart - should it persist across browser sessions?
3. What happens if a payment fails? Should we retry automatically?
4. Do you want inventory tracking (prevent ordering out-of-stock items)?

Please answer these questions, or run:
  bangstack analyze requirements.md --auto-infer
to have me make reasonable assumptions.
```

### Step 3: Answer Questions (Interactive Mode)

```bash
$ bang refine

Question 1: Should customers be able to checkout as guests?
> yes, allow guest checkout

Question 2: Should cart persist across browser sessions?
> yes, save in database for logged-in users, localStorage for guests

Question 3: What happens if payment fails?
> show error message, let them try again

Question 4: Do you want inventory tracking?
> yes, check stock before allowing checkout

✓ Answers recorded. Generating internal specifications...
```

### Step 4: Generate Internal YAML

```bash
$ bang build

Building internal specifications from requirements...

✓ Generated .bangstack/internal/workflows.yaml
✓ Generated .bangstack/internal/events.yaml
✓ Generated .bangstack/internal/components.yaml
✓ Generated .bangstack/internal/stack.yaml
✓ Generated .bangstack/internal/implementation.yaml

Run 'bangstack validate' to check for issues, or
Run 'bang generate' to create implementation code.
```

### Step 5: Validate System Design

```bash
$ bang validate

Validating system design...

✓ All events have producers and consumers
✓ All components have defined responsibilities
✓ All workflows reference valid actors and components
✓ Stack mappings are complete
⚠ Warning: Event 'email_sent' is emitted but not consumed
  → Consider adding analytics tracking for email delivery

1 warning, 0 errors
System design is valid and ready for generation.
```

### Step 6: Generate Implementation

```bash
$ bang generate

Generating implementation from specifications...

📁 Database
  ✓ migrations/001_create_products.sql
  ✓ migrations/002_create_carts.sql
  ✓ migrations/003_create_orders.sql

📁 Backend (Node.js + Express + TypeScript)
  ✓ src/models/Product.ts
  ✓ src/models/Cart.ts
  ✓ src/models/Order.ts
  ✓ src/routes/products.ts
  ✓ src/routes/cart.ts
  ✓ src/routes/checkout.ts
  ✓ src/services/PaymentService.ts
  ✓ src/integrations/StripePayment.ts
  ✓ src/integrations/PayPalPayment.ts
  ✓ src/integrations/KlarnaPayment.ts

📁 Frontend (React + TypeScript + Tailwind)
  ✓ src/pages/HomePage.tsx
  ✓ src/pages/ProductDetailPage.tsx
  ✓ src/pages/CartPage.tsx
  ✓ src/pages/CheckoutPage.tsx
  ✓ src/components/ProductCard.tsx
  ✓ src/components/PaymentSelector.tsx
  ✓ src/context/CartContext.tsx

📁 Tests
  ✓ tests/checkout-flow.test.ts
  ✓ tests/payment-processing.test.ts

📁 Documentation
  ✓ README.md
  ✓ docs/API.md
  ✓ docs/PAYMENT_SETUP.md

Generated 28 files

Next steps:
  1. Set up environment variables (see .env.example)
  2. Run database migrations: npm run migrate
  3. Start development server: npm run dev
  4. Run tests: npm test
```

### Step 7: Review Generated Code

```bash
$ npm run dev

Server running on http://localhost:3000
API running on http://localhost:3001
```

You open the app, test the checkout flow, and notice:
- The checkout button is blue, but you want it green
- The product cards don't show stock quantities

### Step 8: Provide Feedback

You can either:

**Option A: Update requirements.md**
```markdown
## Design Preferences
- Clean, modern design
- Mobile-responsive
- Primary color: Blue (#3B82F6)
- Checkout button should be GREEN for conversion
- Product cards should show stock quantity
```

**Option B: Use the CLI chat**
```bash
$ bang chat

You: The checkout button should be green instead of blue
AI: Got it. Updating the checkout button color to green...
    ✓ Updated CheckoutPage.tsx
    ✓ Updated tailwind.config.js to include green accent

You: Product cards should show how many items are in stock
AI: Adding stock quantity to product cards...
    ✓ Updated ProductCard.tsx to display stock_quantity
    ✓ Updated products API to include stock data

    Refresh your browser to see the changes.
```

### Step 9: Major Feature Addition

Later, you want to add wishlist functionality:

```bash
$ bang chat

You: I want to add wishlist functionality. Customers should be able to save products to a wishlist.

AI: I'll add wishlist functionality. A few questions:
    - Should the wishlist be available for guest users or only logged-in users?
    - Should customers be able to share their wishlist?
    - Should we send reminders about wishlist items?

You: Only logged-in users. No sharing. No reminders for now.

AI: Perfect. I'm adding wishlist functionality to the system.

    Updating internal specifications:
    ✓ Added wishlist component
    ✓ Added events: wishlist_item_added, wishlist_item_removed
    ✓ Updated catalog component to emit wishlist events
    ✓ Added wishlist workflow for logged-in customers
    ✓ Updated stack with wishlist database table

    Generating implementation:
    ✓ migrations/004_create_wishlists.sql
    ✓ src/models/Wishlist.ts
    ✓ src/routes/wishlist.ts
    ✓ src/pages/WishlistPage.tsx
    ✓ src/components/WishlistButton.tsx
    ✓ Updated ProductCard.tsx (added heart icon)
    ✓ tests/wishlist.test.ts

    Generated 7 files, updated 3 files.

    Changes:
    - New database table: wishlists
    - New API endpoints: GET/POST/DELETE /api/wishlist
    - New page: /wishlist
    - Added heart icon to all product cards
    - Wishlist count in navigation header

    Next steps:
    1. Run migration: npm run migrate
    2. Restart dev server: npm run dev

You: Perfect, thanks!
```

### Step 10: View System Overview

```bash
$ bang overview

E-commerce Store (ecommerce-store v1.0.0)
Source: requirements.md

📋 Components (7)
  ✓ catalog         - Product browsing and display
  ✓ cart            - Shopping cart management
  ✓ wishlist        - Save products for later
  ✓ checkout        - Payment processing
  ✓ order_mgmt      - Order lifecycle management
  ✓ email_system    - Transactional emails
  ✓ analytics       - User behavior tracking

🔔 Events (10)
  product_viewed → catalog → analytics
  product_added_to_cart → cart → checkout, analytics
  wishlist_item_added → wishlist → analytics
  cart_viewed → cart → checkout, analytics
  payment_method_selected → checkout → analytics
  payment_completed → checkout → order_mgmt, email_system
  order_created → checkout → order_mgmt, email_system, analytics
  order_status_changed → order_mgmt → email_system
  email_sent → email_system → analytics

👥 Actors (2)
  👤 customer - Browses, purchases, manages wishlist
  👤 admin - Manages orders and inventory

📦 Stack (7 services)
  Stripe, PayPal, Klarna (payments)
  SendGrid (email)
  PostgreSQL (database)
  Redis (cart cache)
  Mixpanel (analytics)

📄 Generated Files: 31
📝 Requirements: 15 items
✓ All components connected
✓ All events have consumers
```

### Step 11: Export to Documentation

```bash
$ bang docs export

Generating documentation from system design...

✓ docs/ARCHITECTURE.md - System architecture overview
✓ docs/EVENT_FLOW.md - Complete event flow diagrams
✓ docs/API_REFERENCE.md - All API endpoints
✓ docs/WORKFLOWS.md - User journey documentation
✓ docs/COMPONENTS.md - Component responsibilities
✓ docs/DEPLOYMENT.md - Deployment instructions

Documentation exported to docs/
```

## Command Reference

### Core Commands

| Command | Description |
|---------|-------------|
| `bang analyze <file>` | Analyze requirements and extract system design |
| `bang refine` | Answer clarifying questions interactively |
| `bang build` | Generate internal YAML specifications |
| `bang validate` | Validate system design for consistency |
| `bang generate` | Generate implementation code |
| `bang chat` | Interactive chat for modifications |
| `bang overview` | Show system overview |
| `bang docs export` | Export documentation |

### Advanced Commands

| Command | Description |
|---------|-------------|
| `bang diff` | Show changes since last generation |
| `bang rollback` | Rollback to previous version |
| `bang test` | Run generated tests |
| `bang deploy` | Deploy to configured environment |

## What You Maintain vs What AI Maintains

### You Maintain
- `requirements.md` - High-level requirements in plain English
- Chat history with the AI
- Feedback on generated implementation
- Decision-making on features and design

### AI Maintains
- `.bangstack/internal/` - All YAML specifications
- Generated code in `src/`
- Tests
- Documentation
- Database migrations

### Shared
- Environment configuration (`.env`)
- Deployment settings
- Custom business logic (you can override generated code)

## The Feedback Loop

```
requirements.md
      ↓
   analyze
      ↓
   questions ←───┐
      ↓          │
   refine        │ (you answer)
      ↓          │
   build    ─────┘
      ↓
   validate
      ↓
   generate
      ↓
  you review
      ↓
   feedback ←────┐
      ↓          │
  update         │ (AI modifies internal YAML)
      ↓          │
  regenerate ────┘
      ↓
    done!
```

This model keeps you in the product owner role while AI handles the technical implementation details.
