Restructure project for crypto intelligence patterns with test infrastructure

.cursor/mcp.json

@@ -0,0 +1,55 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "node",
+      "args": [
+        "scripts/mcp-env.mjs",
+        "npx", "-y", "@modelcontextprotocol/server-github"
+      ]
+    },
+    "docker": {
+      "command": "uv",
+      "args": ["tool", "run", "mcp-server-docker"]
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": {
+        "MEMORY_FILE_PATH": ".cursor/memory/memory.json"
+      }
+    },
+    "supabase": {
+      "command": "node",
+      "args": [
+        "scripts/mcp-env.mjs",
+        "npx", "-y", "@supabase/mcp-server-supabase@latest",
+        "--read-only",
+        "--project-ref=${SUPABASE_PROJECT_REF}"
+      ]
+    },
+    "postgres": {
+      "command": "node",
+      "args": [
+        "scripts/mcp-env.mjs",
+        "npx", "-y", "@modelcontextprotocol/server-postgres",
+        "${DATABASE_URL}"
+      ]
+    },
+    "auth0": {
+      "command": "npx",
+      "args": ["-y", "@auth0/auth0-mcp-server", "run"]
+    },
+    "azure": {
+      "command": "npx",
+      "args": ["-y", "@azure/mcp@latest", "server", "start"]
+    }
+  }
+}

.cursor/rules/code-quality-gate.mdc

@@ -0,0 +1,34 @@
+---
+description: Enforce project conventions when editing agent source code
+globs: examples/*/src/**/*.py
+alwaysApply: false
+---
+
+# Code Quality Gate
+
+When editing Python files in `examples/*/src/`, verify these conventions:
+
+## FastAPI App (`app.py`)
+- Has `/health` endpoint returning `{"status": "ok"}`
+- Uses `lifespan` context manager (not `@app.on_event`)
+- Calls `setup_tracing()` in lifespan
+- All endpoints are `async def`
+- Request/response use Pydantic models
+
+## Agent Nodes
+- Type hints on all function signatures and variables
+- Uses `verbose_log("AgentName", ...)` for debug output
+- State is a `TypedDict` or Pydantic model (not plain dict)
+- Agent functions are async: `async def node(state: State) -> dict`
+- No bare `except:` -- catch specific exceptions
+
+## Imports
+- `agent_common` imported from workspace (`from agent_common.tracing import ...`)
+- No relative imports crossing package boundaries
+
+## Quick Checklist
+- [ ] Type hints on every function
+- [ ] `async def` for all agent nodes and endpoints
+- [ ] `verbose_log()` calls in agent logic
+- [ ] `setup_tracing()` called in app lifespan
+- [ ] `/health` endpoint present

.cursor/rules/git-workflow.mdc

@@ -0,0 +1,37 @@
+---
+description: Git branching strategy, commit message format, and PR workflow
+alwaysApply: true
+---
+
+# Git Workflow
+
+## Branching
+- `main` -- stable, release-ready code
+- `dev` -- integration branch for in-progress work
+- Feature branches off `dev` when needed: `feat/NN-short-name`
+
+## Commit Messages
+Use conventional commits with optional scope:
+
+```
+type(scope): short description
+
+Optional body explaining motivation.
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`
+Scopes: pattern number or area, e.g. `01`, `common`, `infra`, `ci`
+
+Examples:
+- `feat(02): add community analyst agent with MCP tool calls`
+- `test(01): add e2e tests for orchestrator pipeline graph`
+- `docs: expand README with pattern progression overview`
+
+## Pull Requests
+- PRs merge `dev` → `main` after a set of related changes
+- Use the GitHub MCP (`project-0-agent-patterns-lab-github` / `create_pull_request`) -- `gh` CLI is **installed** and can be used as alternative tool
+- Write PR body to a temp file and use `--body-file` if using CLI fallback (PowerShell has no heredocs)
+
+## PowerShell Caveats
+- No heredoc (`<<EOF`) -- write multi-line strings to a temp file instead
+- Use `@" ... "@` here-strings only for simple cases (no special chars)

.cursor/rules/local-environment.mdc

@@ -15,21 +15,40 @@ alwaysApply: true
 ## Python Version Management
 - Python versions managed exclusively by **uv** (`uv python install 3.14`)
 - Do NOT use pyenv, pyenv-win, or system Python
-- uv is installed at `C:\Users\krzys\.local\bin\uv.exe`
-- If uv is not on PATH, add it: `$env:Path = "C:\Users\krzys\.local\bin;$env:Path"`
+- uv executable location: `C:\Users\krzys\.local\bin\uv.exe`
+- Preferred command style in chats and terminal commands: use `uv ...` (not full `uv.exe` path)
+- Verify with: `uv --version`
+- If `uv` is unexpectedly missing, restart Cursor/terminal to reload PATH before using any fallback
+- Fallback only if PATH cannot be updated: `& "C:\Users\krzys\.local\bin\uv.exe" ...`
 - Project is pinned to Python 3.14 via `.python-version` file
 
+## uv Command Consistency
+- Use `uv` for dependency and environment operations across all chats
+- Example (preferred): `uv add --dev pytest-cov`
+- Do not mix styles within one instruction set (avoid switching between `uv` and full path unless fallback is required)
+
 ## Paths
-- Workspace: `C:\Users\krzys\Dev Projects\agent-patterns-lab`
-- uv binary: `C:\Users\krzys\.local\bin\uv.exe`
-- uv-managed Pythons: `C:\Users\krzys\AppData\Roaming\uv\python\`
+- local project workspace: `C:\Users\krzys\Dev Projects\agent-patterns-lab`
+- main curriculum: `agent-patterns-lab\docs\curriculum.md`
+- example folders: `agent-patterns-lab\examples\<example-name>`
+- 
+
+## GitHub CLI (`gh`)
+- Installed: `gh` v2.88.1, authenticated as `ksopyla`
+- Auth scopes: `repo`, `gist`, `read:org`, `admin:public_key`
+- Git operations protocol: SSH
+- Use `gh` for GitHub operations: PRs, issues, actions, releases, API calls
+- Prefer `gh` CLI over the GitHub MCP server when both can do the job -- CLI is faster and more flexible
+- Examples:
+  - `gh pr create --title "..." --body "..."`
+  - `gh issue list --label bug`
+  - `gh run list --workflow ci.yml`
+  - `gh api repos/{owner}/{repo}/actions/runs` for arbitrary API calls
 
 ## Repository
 - GitHub: `git@github.com:ksopyla/agent-patterns-lab.git`
-- Branch: `main`
+- Branch: `main` and `dev` (for development)
 - Remote: `origin`
 
-## LLM Providers
-- Primary: Azure OpenAI (GPT-5 deployment)
-- Secondary: Anthropic (Claude 4.6 Opus)
+## Secret Management
 - Configure via `.env` file (copy from `.env.example`)

.cursor/rules/project-vision.mdc

@@ -0,0 +1,58 @@
+---
+description: Project vision, narrative arc, and use case for the Agent Design Patterns Library
+alwaysApply: true
+---
+
+# Project Vision
+
+For the full narrative, story, and architectural philosophy, see `docs/vision.md`.
+
+**Practical design patterns for distributed multi-agent systems** -- from single-process orchestration to enterprise-grade, cloud-deployed agent architectures.
+
+Terminology: "Pattern", not "Lesson" or "Tutorial". Folder references: `examples/NN-name/`.
+
+## Use Case: Crypto Intelligence Platform
+
+All patterns use a single evolving domain: an intelligence platform for crypto projects with three specialized teams.
+
+### Team 1: Intelligence (Fundamentals Research) -- built in Patterns 01-04
+- **Research Planner** -- analyzes the request, creates a research plan
+- **News Scanner** -- searches for recent news, announcements, partnerships
+- **Project Profiler** -- researches project goals, whitepaper, technology, roadmap (from P02)
+- **Community Analyst** -- monitors social sentiment, GitHub activity (from P02)
+- **Intelligence Compiler** -- synthesizes findings into a structured report
+
+### Team 2: Technical Analysis -- arrives at Pattern 05
+- **Price Collector** -- current/historical price and volume data
+- **Indicator Calculator** -- technical indicators (MA, RSI, MACD, Bollinger)
+- **Level Analyst** -- support/resistance levels, key price zones
+- **Technical Reporter** -- produces technical analysis summary
+
+### Team 3: Trading Signals -- arrives at Pattern 06
+- **Signal Synthesizer** -- combines fundamentals + technical analysis
+- **Risk Assessor** -- evaluates risk from multiple dimensions
+- **Trade Advisor** -- produces buy/sell/hold recommendations with confidence levels
+
+## Pattern Progression
+
+Main path: P01 → P02 → P03 → P05 → P06 → P07 → P08 → P09
+Optional enrichment: P04 branches off P03
+
+| Pattern | Name | Teams | Architectural focus |
+|---------|------|-------|---------------------|
+| 01 | Orchestrator Pipeline | Team 1 (3 agents) | StateGraph, tool use, single process |
+| 02 | MCP Tool Integration | Team 1 (5 agents) | MCP servers/clients, multi-container |
+| 03 | Persistent Memory | Team 1 | Checkpointer, PostgreSQL, threads |
+| 04 | Memory Lifecycle (optional) | Team 1 | Refiner agent, TTL, hierarchical memory |
+| 05 | Distributed A2A | Team 1 + 2 | A2A protocol, Agent Cards, separate services |
+| 06 | Async + Streaming | Team 1 + 2 + 3 | Async tasks, SSE, parallel A2A requests |
+| 07 | Cross-Network Auth | All (Team 2 external) | JWT, Auth0 M2M, separate Docker networks |
+| 08 | Discovery + Observability | All + Whale Tracker | Agent registry, OpenTelemetry, distributed tracing |
+| 09 | Cloud Deployment | All on Azure | Container Apps, Bicep IaC, Managed Identity |
+
+## Key Architectural Decisions
+
+- **FastAPI role evolves**: P01 serves REST `POST /run` → P02 hosts MCP endpoints → P05+ hosts A2A JSON-RPC. HTTP is the transport, not the API paradigm.
+- **No custom UI**: Claude Code / Claude Desktop / Cursor connect to agents via MCP. Agents expose MCP servers and A2A endpoints, not chat widgets.
+- **Each pattern tells a story**: the new team or capability creates a real architectural problem that motivates the pattern. Never introduce a pattern without the narrative reason.
+- **Documentation co-located**: each pattern's `README.md` is the single source of truth.

.cursor/rules/tech-stack.mdc

@@ -9,9 +9,17 @@ alwaysApply: true
 - Python 3.14+, async-first, type hints on all functions and variables
 - Python versions managed by uv (`uv python install 3.14`), NOT pyenv or system installs
 - `.python-version` file pins the project to 3.14
-- Use `ruff` for linting and formatting, `mypy --strict` for type checking
+- Use `ruff` for linting and formatting
 - Use `pytest` with `asyncio_mode = "auto"` for tests
 
+## Linting & Type Checking Commands
+- Lint: `uv run ruff check .`
+- Format check: `uv run ruff format --check .`
+- Type check: `uv run python scripts/linting/run_mypy.py`
+- Tests: `uv run python scripts/testing/run_test_suite.py`
+- **NEVER run `mypy` directly across multiple examples** -- each example has its own `src/` package, so a bare `mypy libs/ examples/` causes "Duplicate module named src" errors. Always use the per-directory wrapper script.
+- When editing `.github/workflows/ci.yml`, use the same scripts listed above -- CI and local dev must run identical commands.
+
 ## uv
 - Use `uv add` to add dependencies (never pip install)
 - Use `uv run` to execute scripts and commands

.cursor/rules/testing-gate.mdc

@@ -0,0 +1,21 @@
+---
+description: Enforce automated tests before commit and in CI
+alwaysApply: true
+---
+
+# Testing Gate
+
+## Required Behavior
+- When code changes in `examples/` or `libs/`, update tests as needed.
+- Keep test structure per example as `tests/unit`, `tests/api`, and `tests/e2e`.
+
+## Canonical Commands
+- Tests: `uv run python scripts/testing/run_test_suite.py`
+- Type check: `uv run python scripts/linting/run_mypy.py`
+- Never run `mypy` directly across multiple examples (causes duplicate module errors).
+- CI (`ci.yml`) must use the same wrapper scripts -- never inline raw tool commands.
+
+## Skill Trigger
+- Use the `tester` skill for test planning, implementation, and maintenance.
+
+

.cursor/settings.json

@@ -0,0 +1,10 @@
+{
+  "plugins": {
+    "supabase": {
+      "enabled": true
+    },
+    "continual-learning": {
+      "enabled": true
+    }
+  }
+}

.cursor/skills/docker-debugger/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: docker-debugger
+description: >-
+  Builds, runs, and debugs Docker Compose setups for examples. Use when Docker
+  builds fail, containers won't start, inter-container networking breaks, or
+  when debugging multi-service agent deployments.
+---
+
+# Docker Debugger
+
+## When to Use
+
+Trigger this skill when:
+- `docker compose up --build` fails or a container exits unexpectedly
+- An agent service can't reach another service (network/DNS issues)
+- Debugging multi-container setups in Patterns 05+
+- Investigating image build failures with the base Dockerfile
+
+## Available MCP Tools
+
+Use the Docker MCP (`project-0-agent-patterns-lab-docker`) for inspection:
+
+| Tool | Purpose |
+|------|---------|
+| `list_containers` | See running/stopped containers and their status |
+| `fetch_container_logs` | Read stdout/stderr from a specific container |
+| `list_images` | Check built images and tags |
+| `list_networks` | Inspect Docker networks for multi-service setups |
+| `list_volumes` | Check persistent volumes (PostgreSQL, etc.) |
+| `start_container` / `stop_container` | Control individual containers |
+| `recreate_container` | Rebuild and restart a single container |
+
+## Diagnostic Workflow
+
+1. **Check container status**
+   - Call `list_containers` to see which containers are running, exited, or restarting
+   - Note exit codes: `0` = clean stop, `1` = app error, `137` = OOM killed
+
+2. **Read logs for the failing container**
+   - Call `fetch_container_logs` with the container name
+   - Look for: import errors, missing env vars, port conflicts, connection refused
+
+3. **Verify network connectivity** (multi-service)
+   - Call `list_networks` to confirm all services share a network
+   - Service DNS names match the `services:` keys in `docker-compose.yml`
+   - Common fix: services on different networks can't reach each other
+
+4. **Check image build**
+   - Call `list_images` to verify the image was built
+   - If missing, the build stage likely failed -- re-read build logs
+
+5. **Fix and rebuild**
+   - Fix the issue in code or config
+   - Run `docker compose up --build` to rebuild
+
+## Project-Specific Build Context
+
+All examples use the base Dockerfile at `infra/docker/base/Dockerfile.agent`:
+- Build context is always the repo root (`../..` from the example)
+- `EXAMPLE_DIR` build arg points to the specific example folder
+- Multi-stage build: `builder` installs deps, `runtime` copies artifacts
+- `.env` file is passed via `env_file` in docker-compose
+
+## Common Failures
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| `ModuleNotFoundError` | Dependency missing in `pyproject.toml` | `uv add <package>` in the example, rebuild |
+| `Connection refused` on port 8000 | App not binding to `0.0.0.0` | Set `--host 0.0.0.0` in uvicorn command |
+| Container restarts in loop | Crash on startup (missing env var) | Check `.env` file, compare with `.env.example` |
+| `network X not found` | Compose network not created | Run `docker compose down` then `up` again |
+| Build fails at `uv sync` | Lock file out of sync | Run `uv lock` locally first, then rebuild |
+
+## Shell Commands (PowerShell)
+
+```powershell
+# Build and run from example directory
+docker compose up --build
+
+# Rebuild single service
+docker compose up --build agent
+
+# View logs for a service
+docker compose logs -f agent
+
+# Full reset (remove containers, networks, volumes)
+docker compose down -v
+```