Beadloom

Appearance

✅ fresh

last synced 2026-06-17T22:39:35.514075+00:00 · coverage 100% (agent-prime)

Validation by Beadloom doc_sync — same source as sync-check.

Agent Prime ​

Cross-IDE context injection via a three-layer architecture.

Layers ​

  1. AGENTS.md (static) — .beadloom/AGENTS.md with MCP tool list, architecture rules, conventions. Regenerated by generate_agents_md(), preserves content below ## Custom marker.

  2. IDE adapters (pointers) — .cursorrules, .windsurfrules, .clinerules files that instruct agents to read AGENTS.md. Created by setup_rules_auto() on bootstrap.

  3. beadloom prime (dynamic) — CLI command and MCP tool that queries the DB for current project state: architecture summary, stale docs, lint violations, domain list.

API ​

prime_context(project_root, *, fmt="markdown") ​

Returns compact project context. Static layer (config, rules, AGENTS.md) always available. Dynamic layer (DB queries) degrades gracefully without DB.

  • fmt="markdown" — human-readable output (~1000-1500 tokens)
  • fmt="json" — structured dict for programmatic use

setup_rules_auto(project_root) ​

Auto-detects IDEs by marker files and creates adapter files. Returns list of created file paths.

generate_agents_md(project_root) ​

Generates .beadloom/AGENTS.md with v2 template. Injects rules from rules.yml. Preserves user content below ## Custom.

setup_mcp_auto(project_root) ​

Auto-detects editor (claude-code, cursor, windsurf) by marker files and creates MCP config. Returns editor name on success, or None if config already exists.

Data Types ​

ScanResult (TypedDict) ​

Result of scan_project() — discovered project structure.

python
class ScanResult(TypedDict):
    manifests: list[str]      # Found manifest files (pyproject.toml, package.json, etc.)
    source_dirs: list[str]    # Discovered source directories
    file_count: int           # Total code file count
    languages: list[str]      # Detected file extensions

ClusterEntry (TypedDict) ​

A two-level directory cluster produced by _cluster_with_children().

python
class ClusterEntry(TypedDict):
    files: list[str]                    # All code files in the cluster
    children: dict[str, list[str]]      # Child dir name → code files
    source_dir: str                     # Owning top-level source directory

CLI ​

  • beadloom prime [--json] [--update] [--project PATH]
  • beadloom setup-rules [--tool cursor|windsurf|cline] [--project PATH]
  • beadloom setup-mcp [--tool claude-code|cursor|windsurf] [--remove] [--project PATH]

MCP ​

  • prime tool (no parameters) — returns JSON context for agent sessions

Source ​

  • src/beadloom/onboarding/scanner/ — cohesion-split package; prime.py (prime_context()), agents_md.py (setup_rules_auto(), generate_agents_md(), setup_mcp_auto()), types.py (ScanResult, ClusterEntry), plus bootstrap.py / init_flow.py / project_scan.py / summary.py / entry_points.py / import_scan.py / readme.py / doc_classify.py / rules_gen.py / claude_md.py / constants.py; the package __init__.py re-exports the full public surface
  • src/beadloom/services/commands/query.py — prime CLI command
  • src/beadloom/services/commands/setup.py — setup-rules and setup-mcp CLI commands
  • src/beadloom/services/mcp_server.py — prime MCP tool