Spec-Driven Development

> User: I want to add a saved credit card feature to our payments API.
  During tokenization, we should be able to return a UUID that represents
  a long term saved card, if requested through the API.
  Users should be able to store their card details securely for faster
  checkout in the future.

  Let's think together about how to implement this.

⏺ Agent: I'd be happy to help design a saved credit card feature for your
  payments API! Let me first explore the current codebase to understand
  the existing architecture, then we can discuss the implementation
  approach together.

⏺ Read(README.md)
  ⎿  Read 340 lines

⏺ Search(pattern: "**/token*.py")
  ⎿  Found 43 files (ctrl+o to expand)

⏺ Read(services/payment-token/src/payment_token/domain/token.py)
  ⎿  Read 432 lines

⏺ Read(services/payment-token/src/payment_token/api/routes.py)
  ⎿  Read 414 lines

⏺ Great! I've explored your payments infrastructure codebase. Now I have
  a good understanding of the current architecture. Let me discuss with
  you how we could implement a saved credit card feature.

  Current State Analysis

  Your payment tokenization system currently:
  - Creates short-lived tokens (24 hours default TTL)
  - Stores encrypted payment data with metadata
  - Returns tokens in format pt_{uuid}

  Design Considerations for Saved Cards

  Let me outline a few approaches we could take...

  Approach 2: Separate Saved Card Entity (Recommended)
  - Create a new SavedPaymentMethod entity with its own UUID (cpm_{uuid})
  - Link to the underlying payment token (which never expires)
  - Stored at customer level, not restaurant level

  Key Questions for You:
  1. Customer Scoping: Should saved cards be scoped to...
  2. Token Format: When returning a saved card, should we...
  3. Expiration: For saved cards, should they...
  4. API Changes: Should the tokenization endpoint...

> Approach 2 makes the most sense to me.
  1. a specific customer (not restaurant)
  2. just a uuid
  3. never expire
  4. accept a save_card flag and customer_id field (optionals)

  let's create a spec for this

⏺ Perfect! Approach 2 with those constraints makes a lot of sense.
  Let me create a comprehensive spec for the saved credit card feature.

⏺ plugin:sudocode:sudocode - upsert_spec (MCP)
  (title: "Saved Credit Card Feature - Customer Payment Methods",
   description: "# Saved Credit Card Feature...
   ...comprehensive spec content...)
  ⎿  { "id": "s-50kd", ... }

⏺ Perfect! I've created a comprehensive specification for the saved
  credit card feature. The spec is now saved at
  specs/s-50kd_saved_credit_card_feature_customer_payment_methods.md

> Great. We left some feedback on the spec, please re-read it.
  Then, create issues for this spec.

⏺ plugin:sudocode:sudocode - show_spec (MCP)(spec_id: "s-50kd")
  ⎿  { "id": "s-50kd", ... }

⏺ I can see the spec has been updated with feedback. Now let me create
  issues for implementing this spec based on the migration phases
  outlined.

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Database schema migration for saved payment methods", ...)
  ⎿  { "id": "i-46dk", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Create SavedPaymentMethod domain entity...", ...)
  ⎿  { "id": "i-78a9", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Create repository methods for saved payment methods", ...)
  ⎿  { "id": "i-923i", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Update token creation endpoint to support save_card flag", ...)
  ⎿  { "id": "i-2vsy", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Implement customer payment methods management endpoints", ...)
  ⎿  { "id": "i-4xwd", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Update authorization API to support cpm_* payment method IDs", ...)
  ⎿  { "id": "i-3iy5", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Comprehensive testing for saved payment methods", ...)
  ⎿  { "id": "i-7klo", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Update frontend demo to support saved cards", ...)
  ⎿  { "id": "i-4da3", ... }

⏺ Excellent! I've created 8 issues that implement the saved credit card
  feature based on the spec. Here's the breakdown:

  Phase 1: Database (Priority 0)
  - i-46dk: Database schema migration

  Phase 2: Domain Layer (Priority 0)
  - i-78a9: Domain entity and model updates
  - i-923i: Repository methods

  Phase 3: API Implementation (Priority 1)
  - i-2vsy: Token creation endpoint updates
  - i-4xwd: Customer payment methods endpoints
  - i-3iy5: Authorization API cpm_* support

  Phase 4: Testing & Demo (Priority 2)
  - i-7klo: Comprehensive testing
  - i-4da3: Frontend demo updates

  All issues are now linked to spec s-50kd with the "implements"
  relationship.

> Can you create dependencies between these issues?

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-46dk", to_id: "i-78a9", type: "blocks")

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-78a9", to_id: "i-923i", type: "blocks")

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-923i", to_id: "i-2vsy", type: "blocks")

  ... [agent creates full dependency graph] ...

⏺ Perfect! I've created the dependency chain between all issues.
  Here's the dependency graph:

  i-46dk (Database migration)
    ↓ blocks
  i-78a9 (Domain models)
    ↓ blocks
  i-923i (Repository layer)
    ↓ blocks (splits into parallel)
    ├─→ i-2vsy (Token creation endpoint)
    └─→ i-4xwd (Customer endpoints)
         both block ↓
       i-3iy5 (Authorization API)
         ↓ blocks (parallel)
       i-7klo (Testing) + i-4da3 (Frontend demo)

# 1. Human describes feature to agent
You: "I want to add [feature description]. Let's design this together."

# 2. Agent explores codebase and proposes approaches
Agent uses MCP tools to understand existing architecture

# 3. Human and agent co-create spec
You: "Approach 2 makes sense. Create a spec for this."
Agent: [Uses upsert_spec() MCP tool to create specification]

# 4. Agent breaks down spec into issues
You: "Create issues for this spec."
Agent: [Uses upsert_issue() and link() to create implementation plan]

# 5. Agents execute issues in dependency order
Dispatch agents from web UI or via MCP ready() queries

# 6. Agents provide feedback during implementation
Agent: [Uses add_feedback() to surface ambiguities]

# 7. Human refines spec based on feedback
Review feedback in web UI, edit spec markdown as needed

# 8. Merge worktree changes as issues complete
Click "Merge Worktree" button to accept agent's work

# 9. New issues created if needed
Agent discovers additional work during implementation

# 10. All issues completed, feature ready for review!

ISSUE-001: Database schema migration
ISSUE-002: Domain model updates
ISSUE-003: Business logic implementation
ISSUE-004: API endpoint creation

Iteration 1:
  Spec: "Build search feature"
  Agent: Implements basic search
  Feedback: "Ranking algorithm not specified"

Iteration 2:
  Spec updated: "Use TF-IDF for ranking"
  Agent: Implements TF-IDF
  Feedback: "Performance on large datasets?"

Iteration 3:
  Spec updated: "Target: <100ms for 10M documents"
  Agent: Optimizes with caching
  Complete!

SPEC-001: E-commerce Platform (epic)
  ├─ SPEC-002: Product Catalog
  │    ├─ ISSUE-010: Product model
  │    ├─ ISSUE-011: Search API
  │    └─ ISSUE-012: Product images
  ├─ SPEC-003: Shopping Cart
  │    ├─ ISSUE-020: Cart model
  │    ├─ ISSUE-021: Add to cart
  │    └─ ISSUE-022: Checkout flow
  └─ SPEC-004: Payment Integration
       ├─ ISSUE-030: Stripe setup
       └─ ISSUE-031: Payment flow