botcore-config

name	botcore-config
source	botcore
description	Guides configuration of botcore projects via botcore.toml or pyproject.toml. Covers BotCoreConfig model, SkillsConfig, PackageOverrideConfig, EnvConfig, language detection and tool defaults, per-package overrides, precedence rules, plugin config validation, and common misconfiguration pitfalls. Use when setting up a new botcore project, configuring thresholds, adding per-package overrides, troubleshooting config-related silent failures, or understanding the config loading flow. Triggers: config, configuration, botcore.toml, pyproject.toml, BotCoreConfig, thresholds, language detection, tool defaults, per-package, SkillsConfig.
version	1.0.0
triggers	["config","configuration","botcore.toml","pyproject.toml","BotCoreConfig","thresholds","language detection","tool defaults","per-package","SkillsConfig","PackageOverrideConfig","EnvConfig","coverage threshold","file size limit","configure botcore"]
portable	true

Configuring Botcore

Expert guidance for configuring botcore behavior through TOML configuration files, environment variables, and per-package overrides.

Capabilities

1. Write Project Config -- Set up botcore.toml or [tool.botcore] in pyproject.toml with correct fields and types
2. Configure Quality Thresholds -- Set file size, coverage, duplication, and dependency staleness limits
3. Add Per-Package Overrides -- Apply different thresholds to specific packages in a monorepo
4. Configure Skills -- Control which skills are included, skipped, or sourced from alternate directories
5. Set Up Plugin Config -- Define plugin-specific configuration sections validated by plugin schemas
6. Understand Precedence -- Know how CLI flags, project config, language defaults, and core defaults layer

Routing Logic

Request Type	Load Reference
All config fields, types, defaults, annotated example	references/config-reference.md
load_config() flow, layered merge, CLI overrides	references/precedence.md
Per-package overrides, get_config_for_path()	references/per-package.md
Language auto-detection, _TOOL_DEFAULTS map	references/language-detection.md

Core Principles

1. Convention Over Configuration

Botcore auto-detects language and applies tool defaults. Only configure what differs from defaults. An empty config section is valid — language detection + defaults handle the common case.

For a standard Python project, botcore auto-detects Python and sets linter=ruff, test_runner=pytest, formatter=ruff without any config.

2. Config Sources Have Clear Precedence

Precedence (highest to lowest): CLI flags → project config → plugin defaults → core defaults. Per-package overrides use REPLACE semantics, not additive merge.

A CLI flag always wins. A per-package coverage_paths=["lib/"] completely replaces the root coverage_paths=["src/"].

3. Fail Fast on Unknown Fields

All config models use `extra="forbid"`. Typos and unknown fields cause immediate validation errors. This prevents silent misconfiguration — a misspelled field name is caught on load.

4. Secrets Stay in Environment

API keys and tokens go in environment variables (`EnvConfig`), never in TOML files. TOML config is committed to the repo. Secrets must not be.

Quick Reference

Minimal Config (usually sufficient)

# pyproject.toml
[tool.botcore]
# Language auto-detected. Defaults applied automatically.

Common Overrides

[tool.botcore]
language = "python"
file_size_warn = 300       # Lines (default: 500)
file_size_error = 600      # Lines (default: 1000)
coverage_threshold = 90    # Percent (default: 80)

Default Thresholds

Field	Default	Unit
file_size_warn	500	lines
file_size_error	1000	lines
coverage_threshold	80	percent
coverage_warn_threshold	60	percent
duplication_threshold	5	occurrences
duplication_min_lines	10	lines
circular_deps_allowed	0	count
deps_max_major_behind	1	versions
deps_max_minor_behind	3	versions

Tool Defaults by Language

Language	Linter	Test Runner	Formatter
Python	ruff	pytest	ruff
TypeScript	biome	vitest	biome
Rust	clippy	cargo-test	rustfmt

Checklist

• Config placed in pyproject.toml [tool.botcore] or standalone botcore.toml
• No unknown fields (would cause validation error)
• Language explicitly set or auto-detection verified
• Quality thresholds appropriate for project maturity
• Per-package overrides use [tool.botcore.packages.NAME] syntax
• Secrets in environment variables, not TOML
• Plugin config sections match installed plugins