# CONTEXT: BDL-014 — Agent Prime (Cross-IDE Context Injection)

> **Phase:** Planning → Development
> **Last updated:** 2026-02-14

---

## Goal

Add `beadloom prime` (CLI + MCP tool) — a single entry point for AI agents to receive compact project context. Three-layer architecture: AGENTS.md (static source of truth) → IDE adapters (thin pointers) → prime (dynamic context).

---

## Key Decisions

| # | Decision | Rationale |
|---|----------|-----------|
| 1 | `prime_context()` lives in `scanner.py` | Next to `generate_agents_md()`, same module, avoids new files |
| 2 | Claude Code hooks are out of scope | User manages `.claude/` themselves; we document but don't auto-write |
| 3 | IDE adapters don't include Claude Code | `.claude/CLAUDE.md` is user-managed; only Cursor/Windsurf/Cline |
| 4 | AGENTS.md `## Custom` section preserved | User edits below marker survive regeneration |
| 5 | Prime reads DB but doesn't run lint | Performance: <500ms target; uses cached data from last reindex |
| 6 | Output ≤2000 tokens | Avoid polluting agent context window |

---

## Architecture

```
.beadloom/AGENTS.md          ← Layer 1: single source of truth
  ↑ generated by generate_agents_md()
  ↑ includes rules from rules.yml

.cursorrules                 ← Layer 2: IDE adapters (thin pointers)
.windsurfrules
.clinerules
  ↑ generated by setup_rules_auto()

beadloom prime (CLI + MCP)   ← Layer 3: dynamic context
  ↑ reads AGENTS.md + DB + rules.yml
  ↑ outputs compact markdown or JSON
```

---

## Related Files

| File | Role |
|------|------|
| `src/beadloom/onboarding/scanner.py` | Core: `prime_context()`, `generate_agents_md()`, `setup_rules_auto()` |
| `src/beadloom/services/cli.py` | CLI: `prime` and `setup-rules` commands |
| `src/beadloom/services/mcp_server.py` | MCP: `prime` tool (#10) |
| `.beadloom/_graph/rules.yml` | Architecture rules (read by prime) |
| `.beadloom/config.yml` | Project name, preset (read by prime) |
| `.beadloom/AGENTS.md` | Generated agent instructions |
| `tests/test_scanner.py` | Tests for scanner functions |
| `tests/test_cli_*.py` | CLI integration tests |

---

## Code Standards

### Language and environment
- **Language:** Python 3.10+ (type hints, `str | None` syntax)
- **Package manager:** uv
- **Virtual environment:** uv venv

### Methodologies
| Methodology | Application |
|-------------|-------------|
| TDD | Red → Green → Refactor for each bead |
| Clean Code | Naming (snake_case), SRP, DRY, KISS |
| Modular architecture | CLI → Core → Storage, dependencies point inward |

### Testing
- **Framework:** pytest + pytest-cov
- **Coverage:** minimum 80%
- **Fixtures:** conftest.py, tmp_path

### Code quality
- **Linter:** ruff (lint + format)
- **Typing:** mypy --strict

### Restrictions
- [x] No `Any` without justification
- [x] No `print()` / `breakpoint()` — use logging
- [x] No bare `except:` — only `except SpecificError:`
- [x] No `os.path` — use `pathlib.Path`
- [x] No f-strings in SQL — parameterized queries `?`
- [x] No `yaml.load()` — only `yaml.safe_load()`
- [x] No magic numbers — extract into constants
