aifolimizer - Project Context

Session Startup (read every new session)

1. Read .claude/context/changes.md - what built, when
2. Read .claude/context/architecture.md - data flow, API contracts, file index
3. Read .claude/context/lessons.md - past corrections, do-not-repeat rules
4. Call mcp__aifolimizer__get_profile before analysis - never hardcode account types or capital

What This Is

AI investment advisor for Canadian Wealthsimple retail investors (growth+income+crypto profile). Live portfolio via local backend. AI analysis in Claude Code/Desktop Pro - no Anthropic API key.

Architecture

Claude Code / Claude Desktop  (Pro subscription - no API key)
        ↓ invokes
   .claude/skills/*  (28 institutional analysis skills)
        ↓ calls MCP tool
   backend/mcp_server.py  (FastMCP, 107 tools)
        ↓ uses
   app/services/{wealthsimple, market_data, fundamentals, technicals, news, macro, quant, portfolio_analytics, health_score, crypto_data}
        ↓ HTTP
   Wealthsimple + yfinance + FRED + CoinGecko (all free, no keys required)

No frontend - analysis runs in Claude Code / Claude Desktop. FastAPI is exposed for ad-hoc REST testing only.

How to Start

Fresh clone: ./setup.sh (POSIX/Git-Bash) or powershell -File setup.ps1 (Windows) - venv, deps, backend/.env, .mcp.json, MCP registration, doctor. Idempotent. Then python backend/scripts/health_check.py to diagnose.

# Backend (FastAPI + shared session store)
cd backend && .venv/Scripts/activate && uvicorn main:app --reload --port 8000

MCP server (mcp_server.py) runs as separate process managed by Claude Code - register once with:

claude mcp add aifolimizer "<venv_python_path>" "backend/mcp_server.py"

Quality gates (run before claiming "done"):

pytest                     # testpaths=backend/tests (run from repo root)
ruff check . ; pyright     # lint + type-check

MCP Tools (107 total - table below is a curated subset; see mcp_server.py for full list)

L1+L2: in-process dict + cross-process diskcache. MCP+FastAPI share L2.

Analysis Skills (28 in .claude/skills/ - table below highlights core 13)

Each skill: auto-triggers from frontmatter, calls get_profile FIRST.

Investor Profile (verify with get_profile)

• Canadian retail investor
• Philosophy: growth stocks, index ETFs (XEQT/VFV), dividends, crypto
• Risk: mixed - conservative (bonds/GIC), moderate (ETFs), aggressive (stocks, crypto)
• Horizons: day trading + short-term (<3yr) + long-term (10yr+)
• Tax: TFSA (tax-free), RRSP (tax-deferred), Non-Reg (50% cap gains inclusion)
• Capital + balances: ALWAYS pull from get_profile - never hardcode
• Crowding: before adding to name, call get_positioning_signals. Score ≥70 = consensus-crowded → negative expected alpha. Defer adds; favor contrarian (score ≤30) when fundamentals support.

Tech Stack

Supports Python 3.12-3.14 (uses ta, not pandas-ta); 3.13 recommended. CI + the hash-locked requirements.lock target 3.12.

Privacy Rules (NON-NEGOTIABLE)

Environment Variables

# backend/.env (local only - never commit)
WS_EMAIL=...
WS_PASSWORD=...
# Optional: Telegram alerts, free-LLM fallback keys, Sentry - see .env.example

Code Rules

• No hardcoded capital amounts or account types - always read from get_profile
• No PII in logs, DB, or MCP output
• Activate PII pre-commit hook once per clone: git config core.hooksPath .githooks. Hook blocks owner-identifying strings (gmail, full-name, legacy IDs); allowlist for LICENSE/README/pyproject.toml. CI runs gitleaks with same rules from .gitleaks.toml.
• Functions short, single-purpose
• No comments explaining WHAT - only WHY when non-obvious
• Append to .claude/context/changes.md after significant changes
• Skills builder: python backend/scripts/build_skills.py lists tools + skills
• Scaffold skill: python backend/scripts/build_skills.py --scaffold <tool_name>

Workflow Rules

• Verify before "done." Compile-clean ≠ working. Run import-check (backend) AND exercise w/ real input.
• Lessons loop. After correction or surprise bug, append rule to .claude/context/lessons.md.
• Pause for elegance on non-trivial changes (3+ files or new abstraction). Ask "cleaner path?" before commit.
• Surgical changes only. Touch only what request requires. Match existing style. Remove only imports/vars your changes made unused.
• Targeted reads only. Use semantic_search_nodes or get_review_context before Grep/Read. Read only relevant lines. Ask before loading large files, logs, generated files, or full dependency trees.
• Summarize tool output. Never paste full logs. Extract relevant; drop rest.
• Final answer format: changes made + verification + blockers only.

Commit Rules

• NEVER add Co-Authored-By: Claude ... trailer to commits
• NEVER add "Generated with Claude Code" footer or AI-attribution to commits, PRs, or PR bodies
• Commit messages authored solely by human user

No AI Tone (repo-wide, non-negotiable)

• No AI tone or signs of AI authorship anywhere in the repo: docs, code comments, commit messages, PR text, release notes, the GitHub About.
• No em dashes or en dashes (use -, a comma, or a colon). No words like delve, robust, seamless, comprehensive, leverage, elevate, excels, unleash. No emoji-stuffing, no "not X, but Y" cadence, no redundant restatement, no breathless run-ons.
• No narration of the AI/agent process in committed text (no "parallel audit", "the agent found", "verified by analysis").
• Write plainly, like a human engineer.