ChooChoo for Claude Cowork.

# CLAUDE.md
# Generated by ChooChoo. Do not edit by hand.
# Run: choochoo context generate

## What this is
payments-api: a FastAPI service handling financial
transactions. Provides Claude Code with structured
startup context for this repository.

## Commands
mise run dev     Start dev server (hot-reload on)
mise run test    Full test suite (pytest -v)
mise run lint    Ruff lint check
mise run fix     Auto-fix lint + format

## Code Standards
- Python 3.12 with strict mypy; no untyped Any
- Ruff formatting (line-length = 100)
- Pydantic models for all API inputs/outputs
- Tests required for all new business logic

## Guardrails
- Never log secrets, payment tokens, or card data
- SQL through SQLAlchemy ORM; no raw strings
- All external inputs validated at the API boundary

## Architecture
ADR-001  JWT (RS256); keys in secrets manager
ADR-007  API versioned under /v1/, /v2/ namespaces

{
  "permissions": {
    "allow": [
      "Bash(mise run test*)",
      "Bash(mise run lint*)",
      "Bash(mise run fmt*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git branch*)",
      "Bash(uv run pytest*)",
      "Read",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(git checkout -- *)",
      "Bash(curl*)",
      "Bash(wget*)",
      "Bash(docker rm*)",
      "Bash(DROP TABLE*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "choochoo guard check-command"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "choochoo guard lint-changed"
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "choochoo guard verify-done"
        }]
      }
    ]
  },
  "env": {
    "CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD": "1"
  }
}

# SKILLS.md
# Generated by ChooChoo. Do not edit by hand.

## auth
JWT token lifecycle: creation, validation, refresh.
  Entry: src/auth/service.py
  Tests: tests/auth/

## payments
Stripe integration: charges, subscriptions, webhooks.
  Entry: src/payments/processor.py
  Note:  Never log STRIPE_KEY or card numbers

## database
SQLAlchemy sessions and query patterns.
  Entry: src/db/session.py
  Rule:  Always use get_db() dependency injection

## notifications
Email (SendGrid) and SMS (Twilio) dispatch.
  Entry: src/notifications/dispatch.py

# PLAN.md
# Generated by ChooChoo. Do not edit by hand.

## Goal
Refactor the authentication service to support
multi-factor authentication (MFA) via TOTP.

## Steps
1. [ ] Add TOTP secret column to users table
       migration: src/db/migrations/0023_add_totp.py
2. [ ] Implement TOTP validation in auth service
       src/auth/service.py → verify_totp()
3. [ ] Add /auth/mfa/setup and /auth/mfa/verify routes
       src/api/auth.py
4. [ ] Write unit tests for new MFA paths
       tests/auth/test_mfa.py (≥ 90% coverage)
5. [ ] Update AGENTS.md with new ADR-012

## Constraints
- Do not break existing JWT flow (ADR-001)
- TOTP secrets encrypted at rest (AES-256)
- Rate-limit /auth/mfa/verify to 5 attempts / 15 min

# ARCHITECTURE.md
# Generated by ChooChoo. Do not edit by hand.

## System Overview
payments-api is a stateless FastAPI service.
All state lives in PostgreSQL (primary data) and
Redis (sessions, rate limiting, event streams).

## Request Flow
Client → API Gateway → FastAPI → Service Layer
                                → Repository Layer
                                → PostgreSQL / Redis

## Key Modules
src/auth/        JWT issuance + TOTP (ADR-001, ADR-012)
src/payments/    Stripe integration (charges, webhooks)
src/db/          SQLAlchemy sessions + migration runner
src/api/         Route definitions (v1 + v2 namespaces)

## ADR Index
ADR-001  RS256 JWT for authentication
ADR-004  Redis Streams for webhook event bus
ADR-007  URL versioning (/v1/, /v2/)
ADR-012  TOTP-based MFA (in progress)

## Deployment
Docker → ECS Fargate  (app)
RDS PostgreSQL 15      (primary)
ElastiCache Redis 7    (cache + streams)

# GOAL.md
# Generated by ChooChoo. Do not edit by hand.

## Current Sprint Goal
Implement MFA support without breaking existing
single-factor authentication flows.

## Success Criteria
- All existing auth tests continue to pass
- New /auth/mfa/* endpoints return correct responses
- TOTP validation rejects tokens older than 30 s
- Coverage for src/auth/ stays above 90%

## Out of Scope
- SMS-based MFA (deferred to ADR-013)
- Admin UI for MFA management (separate ticket)
- Recovery codes (phase 2)

## Definition of Done
- PR reviewed and approved
- CI green (lint + test + coverage)
- AGENTS.md updated with ADR-012 summary
- Deployed to staging and smoke-tested

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-23T14:30:00Z",
  "vcs": {
    "type": "git",
    "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  },
  "tool": { "name": "cursor", "version": "2.4.0" },
  "files": [
    {
      "path": "src/utils/parser.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [
            {
              "start_line": 42,
              "end_line": 67,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ],
          "related": [
            {
              "type": "session",
              "url": "https://api.cursor.com/v1/sessions/67890"
            }
          ]
        }
      ]
    },
    {
      "path": "src/utils/helpers.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "openai/gpt-4o"
          },
          "ranges": [
            { "start_line": 10, "end_line": 25 }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "confidence": 0.95,
    "dev.cursor": { "workspace_id": "ws-abc123" }
  }
}