0e78e5b06b
Backend: - ConversationTracker: Protocol + PostgresConversationTracker for lifecycle tracking - Error handler: ErrorCategory enum, classify_error(), with_retry() exponential backoff - Wire PostgresAnalyticsRecorder + ConversationTracker into ws_handler - Rate limiting (10 msg/10s per thread), edge case hardening - Health endpoint GET /api/health, version 0.5.0 - Demo seed data script + sample OpenAPI spec Frontend (all new): - React Router with NavBar (Chat / Replay / Dashboard / Review) - ReplayListPage + ReplayPage with ReplayTimeline component - DashboardPage with MetricCard, range selector, zero-state - ReviewPage for OpenAPI classification review - ErrorBanner for WebSocket disconnect handling - API client (api.ts) with typed fetch wrappers Infrastructure: - Frontend Dockerfile (multi-stage node -> nginx) - nginx.conf with SPA routing + API/WS proxy - docker-compose.yml with frontend service + healthchecks - .env.example files (root + backend) Documentation: - README.md with quick start and architecture - Agent configuration guide - OpenAPI import guide - Deployment guide - Demo script 48 new tests, 449 total passing, 92.87% coverage
297 lines
12 KiB
Markdown
297 lines
12 KiB
Markdown
# Smart Support -- Project Instructions
|
|
|
|
## Project Overview
|
|
|
|
AI customer support action-layer framework. Core value: "Paste your API, get an AI agent that executes real actions."
|
|
|
|
- **Tech Stack:** Python 3.11+, FastAPI, LangGraph v1.1, React, PostgreSQL 16, Docker Compose
|
|
- **Planning Docs:** `docs/DEVELOPMENT-PLAN.md`, `docs/ARCHITECTURE.md`, `eng-review-plan.md`
|
|
- **Phases:** 5 phases (see `docs/DEVELOPMENT-PLAN.md`)
|
|
|
|
---
|
|
|
|
## Phase Execution Workflow (MANDATORY)
|
|
|
|
Every phase MUST follow this exact workflow. No exceptions.
|
|
|
|
### Step 0: Pre-flight Checks, Checkpoint, and Branch
|
|
|
|
Before starting ANY phase work:
|
|
|
|
```bash
|
|
# 1. Verify ECC hooks are working
|
|
# - ECC plugin provides all hooks (quality-gate, security, session management)
|
|
# - Controlled by ECC_HOOK_PROFILE env var (standard/strict) in ~/.claude/settings.json
|
|
# - Run a test edit on a .py file to confirm quality-gate.js fires (ruff auto-format)
|
|
# - If hooks are broken, check ECC plugin status before proceeding
|
|
|
|
# 2. Run full test suite to confirm main is green (regression gate)
|
|
pytest --cov=app --cov-report=term-missing
|
|
# - If any test fails, fix it before starting the new phase
|
|
|
|
# 3. Create checkpoint to snapshot the starting state
|
|
/everything-claude-code:checkpoint create "phase-name"
|
|
|
|
# 4. Create the phase branch
|
|
git checkout main
|
|
git pull origin main
|
|
git checkout -b phase-{N}/{short-description}
|
|
# Example: phase-1/core-framework
|
|
|
|
# 5. Mark phase as IN PROGRESS
|
|
# Update the Phase Summary table in this CLAUDE.md:
|
|
# change Status from `NOT STARTED` to `IN PROGRESS`
|
|
```
|
|
|
|
### Step 1: Read Plan and Prepare
|
|
|
|
1. Read `docs/DEVELOPMENT-PLAN.md` -- locate the current phase section
|
|
2. Read `docs/ARCHITECTURE.md` -- understand relevant components
|
|
3. Identify all tasks, acceptance criteria, and dependencies for this phase
|
|
4. Create a phase dev log **skeleton** at `docs/phases/phase-{N}-dev-log.md` (date, branch name, plan link only -- content filled in Step 5)
|
|
|
|
### Step 2: Develop Using Orchestrate Skill
|
|
|
|
Route to the correct orchestration mode based on work type:
|
|
|
|
| Work Type | Skill Command |
|
|
|-----------|---------------|
|
|
| New feature | `/everything-claude-code:orchestrate feature` |
|
|
| Bug fix | `/everything-claude-code:orchestrate bugfix` |
|
|
| Refactor | `/everything-claude-code:orchestrate refactor` |
|
|
|
|
ALWAYS use the appropriate orchestrate skill. Never develop without it.
|
|
|
|
A single phase may contain mixed work types (e.g., Phase 5 has feature + bugfix + refactor). Call the orchestrate skill **per sub-task** with the matching mode. Example:
|
|
|
|
```
|
|
# Within Phase 5:
|
|
/everything-claude-code:orchestrate feature # for demo script
|
|
/everything-claude-code:orchestrate bugfix # for error handling fixes
|
|
/everything-claude-code:orchestrate refactor # for code cleanup
|
|
```
|
|
|
|
### Step 3: Module Independence (CRITICAL)
|
|
|
|
Every module MUST be independently runnable (with mocked deps) and independently testable. Use `Protocol` for interfaces and dependency injection for all external deps (see `~/.claude/rules/python/patterns.md`). No circular imports -- dependency graph must be a DAG.
|
|
|
|
Module boundaries for this project:
|
|
|
|
```
|
|
backend/app/
|
|
agents/ -- Agent definitions and tools (depends on: registry)
|
|
registry.py -- YAML agent registry (depends on: nothing)
|
|
graph.py -- LangGraph supervisor (depends on: agents, registry)
|
|
openapi/ -- OpenAPI parser + MCP gen (depends on: nothing)
|
|
replay/ -- Conversation replay API (depends on: nothing, reads DB)
|
|
analytics/ -- Analytics queries (depends on: nothing, reads DB)
|
|
callbacks.py -- Token usage logging (depends on: nothing)
|
|
main.py -- FastAPI entry point (composes all modules)
|
|
frontend/ -- React UI (depends on: backend API contract only)
|
|
```
|
|
|
|
### Step 4: Testing (MANDATORY -- 80%+ Coverage)
|
|
|
|
Follow `~/.claude/rules/python/testing.md` for pytest patterns and `pytest.mark` categorization. Use these project-specific markers:
|
|
|
|
```python
|
|
@pytest.mark.unit # per-module isolated tests
|
|
@pytest.mark.integration # cross-module with real PostgreSQL (Docker)
|
|
@pytest.mark.e2e # full-stack user flow tests
|
|
```
|
|
|
|
E2E scope by phase:
|
|
- **Phase 1:** Backend-only E2E via FastAPI TestClient (WebSocket chat loop). Frontend and backend develop in parallel, full-stack E2E not yet possible.
|
|
- **Phase 2+:** Full-stack E2E (frontend + backend) required for all critical user flows.
|
|
|
|
Test file structure:
|
|
|
|
```
|
|
backend/tests/
|
|
unit/ -- @pytest.mark.unit per module
|
|
integration/ -- @pytest.mark.integration with real DB
|
|
e2e/ -- @pytest.mark.e2e full-stack flows
|
|
conftest.py -- Shared fixtures, marker registration
|
|
```
|
|
|
|
**NOTE:** This project uses `--cov=app` (not `--cov=src` as in the global Python rules):
|
|
|
|
```bash
|
|
pytest --cov=app --cov-report=term-missing
|
|
pytest -m unit # run only unit tests
|
|
pytest -m integration # run only integration tests
|
|
pytest -m e2e # run only e2e tests
|
|
```
|
|
|
|
### Step 5: Phase Development Documentation
|
|
|
|
Fill in the dev log skeleton created in Step 1 (`docs/phases/phase-{N}-dev-log.md`):
|
|
|
|
```markdown
|
|
# Phase {N}: {Title} -- Development Log
|
|
|
|
> Status: IN PROGRESS | COMPLETED
|
|
> Phase branch: `phase-{N}/{short-description}`
|
|
> Date started: YYYY-MM-DD
|
|
> Date completed: YYYY-MM-DD
|
|
> Related plan section: [Phase {N} in DEVELOPMENT-PLAN](../DEVELOPMENT-PLAN.md#phase-{n}-xxx)
|
|
|
|
## What Was Built
|
|
|
|
- List of features/components implemented
|
|
- Architecture decisions made during development
|
|
|
|
## Code Structure
|
|
|
|
- New files created and their purposes
|
|
- Modified files and what changed
|
|
- Module dependency changes
|
|
|
|
## Test Coverage
|
|
|
|
- Unit test count and coverage %
|
|
- Integration test count
|
|
- E2E test count
|
|
- Overall coverage: XX%
|
|
|
|
## Deviations from Plan
|
|
|
|
- Any changes from the original plan and why
|
|
|
|
## Known Issues / Tech Debt
|
|
|
|
- Items deferred to future phases
|
|
```
|
|
|
|
Add a link to this dev log in `docs/DEVELOPMENT-PLAN.md` under the corresponding phase section.
|
|
|
|
### Step 6: Verification and Checkpoint Verify
|
|
|
|
After all development and testing, run verification in this exact order:
|
|
|
|
```
|
|
# 1. Run the verification skill -- must pass
|
|
/everything-claude-code:verify
|
|
|
|
# 2. Verify the checkpoint -- validates all phase deliverables
|
|
/everything-claude-code:checkpoint verify "phase-name"
|
|
```
|
|
|
|
The checkpoint verify validates:
|
|
- All tests passing (80%+ coverage)
|
|
- Phase dev log exists and is linked
|
|
- No unresolved TODOs for this phase
|
|
- Module independence constraints met
|
|
- Code quality checks pass
|
|
|
|
Both MUST pass before proceeding. Fix any issues found.
|
|
|
|
### Step 7: Mark Complete, Merge to Main
|
|
|
|
After both verify steps pass:
|
|
|
|
```bash
|
|
# Ensure all changes are committed on the phase branch
|
|
# IMPORTANT: Never use `git add -A`. Add specific files to avoid committing
|
|
# .env, __pycache__, IDE configs, or other untracked artifacts.
|
|
# Verify .gitignore covers all exclusions before staging.
|
|
git add backend/ frontend/ docs/ docker-compose.yml pyproject.toml
|
|
git status # review staged files before committing
|
|
git commit -m "feat: complete phase {N} -- {description}"
|
|
|
|
# Tag the checkpoint
|
|
git tag checkpoint/phase-{N}
|
|
|
|
# Merge to main
|
|
git checkout main
|
|
git merge phase-{N}/{short-description}
|
|
|
|
# Push (after user confirmation)
|
|
git push origin main --tags
|
|
```
|
|
|
|
**Mark phase as completed (MANDATORY -- do ALL four):**
|
|
|
|
1. **Check off tasks** in `docs/DEVELOPMENT-PLAN.md`: mark all completed task checkboxes `- [x]` under the current phase section
|
|
2. **Add phase completion marker** in `docs/DEVELOPMENT-PLAN.md`: add `> Status: COMPLETED (YYYY-MM-DD)` line under the phase heading
|
|
3. **Update dev log** (`docs/phases/phase-{N}-dev-log.md`): fill in `Date completed` and set status to `COMPLETED`
|
|
4. **Update Phase Summary table** in this file (`CLAUDE.md`): change Status from `IN PROGRESS` to `COMPLETED (YYYY-MM-DD)`
|
|
|
|
`docs/DEVELOPMENT-PLAN.md` is the authoritative source for phase status. The CLAUDE.md table is a convenience summary that must stay in sync.
|
|
|
|
All four markers must be consistent. If any is missed, the next phase's Step 0 regression gate will catch the discrepancy.
|
|
|
|
A checkpoint includes:
|
|
- `/everything-claude-code:checkpoint create` at phase start
|
|
- `/everything-claude-code:checkpoint verify` at phase end
|
|
- All tests passing (80%+ coverage)
|
|
- Phase dev log written and linked
|
|
- `/everything-claude-code:verify` passed
|
|
- Git tag `checkpoint/phase-{N}` created
|
|
- Phase marked COMPLETED in four locations
|
|
- Branch merged to main
|
|
|
|
---
|
|
|
|
## Phase Summary
|
|
|
|
| Phase | Branch | Focus | Status |
|
|
|-------|--------|-------|--------|
|
|
| 1 | `phase-1/core-framework` | FastAPI + LangGraph + React chat loop + PostgresSaver | COMPLETED (2026-03-30) |
|
|
| 2 | `phase-2/multi-agent-safety` | Supervisor routing + interrupts + templates | COMPLETED (2026-03-30) |
|
|
| 3 | `phase-3/openapi-discovery` | OpenAPI parsing + MCP generation + SSRF protection | COMPLETED (2026-03-30) |
|
|
| 4 | `phase-4/analytics-replay` | Replay API + analytics dashboard | COMPLETED (2026-03-31) |
|
|
| 5 | `phase-5/polish-demo` | Error hardening + demo prep + Docker deploy | COMPLETED (2026-03-31) |
|
|
|
|
Status values: `NOT STARTED` -> `IN PROGRESS` -> `COMPLETED (YYYY-MM-DD)`
|
|
|
|
---
|
|
|
|
## Rules Reference
|
|
|
|
This project inherits from `~/.claude/rules/`. CLAUDE.md only contains project-specific overrides -- do NOT duplicate rules content here.
|
|
|
|
| Rule File | Project Override |
|
|
|-----------|-----------------|
|
|
| `common/coding-style.md` | None -- follow as-is |
|
|
| `python/coding-style.md` | Use `ruff` only (not black + isort separately) |
|
|
| `python/patterns.md` | `Protocol` for all module interfaces. Module boundary map above |
|
|
| `python/testing.md` | `--cov=app` (not `--cov=src`). Add `@pytest.mark.e2e` marker |
|
|
| `python/security.md` | `bandit` scan recommended before phase merge |
|
|
| `python/hooks.md` | All hooks provided by ECC plugin (see below). Type checker deferred to Phase 2+ |
|
|
| `common/testing.md` | 80%+ coverage enforced by workflow Step 6 verify |
|
|
| `common/security.md` | ECC `governance-capture.js` + `block-no-verify` handle security checks |
|
|
|
|
### Hooks (ECC Plugin -- No Custom Hooks)
|
|
|
|
All hooks come from the ECC plugin (`everything-claude-code`). No project-level hooks in `.claude/settings.local.json`.
|
|
|
|
| ECC Hook | Type | What It Does |
|
|
|----------|------|-------------|
|
|
| `quality-gate.js` | PostToolUse (Edit/Write) | Auto-runs ruff check + format on .py files |
|
|
| `post-edit-format.js` | PostToolUse (Edit) | Auto-format after edits |
|
|
| `block-no-verify` | PreToolUse (Bash) | Blocks `--no-verify` flag on git commits |
|
|
| `governance-capture.js` | Pre+Post (Bash/Edit/Write) | Captures secrets/policy violations (enable: `ECC_GOVERNANCE_CAPTURE=1`) |
|
|
| `pre-bash-git-push-reminder.js` | PreToolUse (Bash) | Confirms before git push |
|
|
| `suggest-compact.js` | PreToolUse (Edit/Write) | Suggests context compaction when needed |
|
|
| `session-end.js` | Stop | Persists session state |
|
|
| `evaluate-session.js` | Stop | Extracts reusable patterns |
|
|
| `cost-tracker.js` | Stop | Tracks token/cost metrics |
|
|
| `check-console-log.js` | Stop | Checks for debug statements |
|
|
| `mcp-health-check.js` | Pre + PostFailure | MCP server health monitoring |
|
|
|
|
Controlled by `ECC_HOOK_PROFILE` env var in `~/.claude/settings.json` (currently: `standard`).
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
- Plan doc: `docs/DEVELOPMENT-PLAN.md`
|
|
- Architecture doc: `docs/ARCHITECTURE.md`
|
|
- Phase dev logs: `docs/phases/phase-{N}-dev-log.md`
|
|
- Test command: `pytest --cov=app --cov-report=term-missing`
|
|
- **Phase start:** `/everything-claude-code:checkpoint create "phase-name"`
|
|
- **Phase end:** `/everything-claude-code:checkpoint verify "phase-name"`
|
|
- Verify command: `/everything-claude-code:verify`
|
|
- Orchestrate: `/everything-claude-code:orchestrate {feature|bugfix|refactor}`
|