beeweave: Instructions file for Codex

BeeWeave — Development Agent Context

This file is for Agents working on the BeeWeave repository itself. It is not the runtime context installed into user projects. User-project context is generated from bootstrap/AGENTS.md by bwe setup.

Project Role

BeeWeave is an Agent-native knowledge workbench. The repository contains the tooling, skills, bootstrap templates, documentation, tests, and OpenSpec changes needed to install and maintain that workbench.

Runtime vault/ and workbench/ directories are not committed to this repository. They are generated in user-selected locations by setup.

Source Layout

beeweave/       # Python CLI and helpers
.skills/        # Agent skill source files
bootstrap/      # User-project bootstrap templates and agent rules
extensions/     # Browser extension and related assets
tests/          # Pytest suite
openspec/       # Proposed and active change specs
setup.sh        # Source-checkout setup path
pyproject.toml  # Packaging and CLI entrypoint

Development Rules

• Keep implementation changes scoped to the active request or OpenSpec change.
• Prefer existing CLI/setup/skill patterns over new abstractions.
• Keep beeweave/cli.py as a lifecycle-only entrypoint. Parser infrastructure belongs in beeweave/commanding.py; command arguments, interaction, and presentation belong in the explicitly registered beeweave/commands/ modules.
• Resolve home, cwd, package data, config paths, and environment through the immutable AppContext at command execution time. Do not add import-time path globals or turn the context into a service locator.
• Keep argparse.Namespace in command adapters. Setup and other multi-step use cases must cross into application/domain code through typed immutable options and results. Application and domain modules must not import argparse, command modules, Rich, InquirerPy, or terminal UI helpers.
• Route setup installation changes through SetupService and its plan/execution components. Upgrade replay must construct SetupOptions and use the same service instead of emulating CLI arguments.
• For terminal interaction in the BeeWeave CLI, route shared presentation through beeweave/ui.py instead of adding ad hoc ANSI, Rich tables, prompts, banners, or summary rendering in command handlers.
• Rich is the shared rendering layer for human-readable CLI output. Keep all Rich object construction behind beeweave/ui.py helpers, and keep plain fallbacks readable.
• Use the shared UI helpers consistently:
  • ui.print_setup_banner for the setup banner.
  • ui.select_prompt for interactive profile-style selections.
  • ui.checkbox_prompt for multi-select flows such as agent and optional global skill selection.
  • ui.text_prompt for validated text input, including new profile names and high-risk confirmation text.
  • ui.confirm_prompt for yes/no confirmations.
  • ui.print_summary_panel for human-facing completion or status summaries.
• Keep InquirerPy optional. Non-interactive and missing-InquirerPy fallbacks must remain deterministic, scriptable, and prompt-free unless the command is explicitly unsafe without interactive confirmation.
• Respect NO_COLOR and non-TTY output. Shared UI helpers must disable ANSI and avoid Rich-only structure in those cases while keeping output readable.
• Current CLI UI conventions:
  • bwe setup uses the shared banner, profile select, new-profile text input, agent/global-skill checkboxes, and setup summary panel.
  • bwe info uses the shared summary panel.
  • bwe uninstall uses shared confirmation and completion summary panel.
  • bwe profile set-default uses shared high-risk text confirmation and completion summary panel.
• Do not add banners or panels to machine-readable commands such as graph-query, graph-analyse, batch-plan, cache-check, cache-update, cache-hash, ast-extract, or list; preserve their JSON/plain-text output for scripts and pipes.
• Register new commands explicitly in beeweave/commands/__init__.py so help order remains deterministic. Do not add module scanning, decorators, or entry-point discovery for built-in commands.
• Use apply_patch for manual file edits.
• Do not recreate runtime vault/ or workbench/ directories in the repo root.
• Preserve user work and unrelated dirty files.
• Keep generated user-project instructions in bootstrap/AGENTS.md, not here.