bot-bottle/AGENTS.md

bot-bottle

What this is

bot-bottle spins up an isolated container for running AI coding agents with a curated set of skills and env vars. The point is to run agents with broad permissions inside a sandbox, so a misbehaving agent cannot reach the host. A Python CLI (entry point cli.py, package bot_bottle/) orchestrates the container lifecycle and the copying of skills and env vars into it.

Goals

• Minimize risk of running agents with full permissions
• Allow me to easily spin up agent tasks in parallel
• Create isolated, well defined, easily updated, shareable agents

Non-goals

• Communicating between agents directly
• Self hosted VMs (v1 uses local Docker containers, not VMs)
• Advanced agent auditing (lean on git history for auditing)

Repository layout

• README.md — short public-facing description.
• AGENTS.md — this file, orientation for future agent sessions.
• .gitignore — OS junk.
• bot-bottle.json — legacy manifest of named agents (env / skills / prompt per agent), consumed by cli.py. See "Manifest" under "Intended design".
• docs/README.md — docs overview; when to write which document.
• docs/prds/ — product requirement docs (see docs/prds/README.md for format).
• docs/research/ — research notes (see docs/research/README.md).
• docs/decisions/ — decision records (ADR-lite).

Conventions

• Three kinds of doc, each with its own conventions in-folder; see docs/README.md for when to write which:
  • PRDs (docs/prds/) — one feature per file, numbered NNNN-kebab.md. A Status: line tracks lifecycle: Draft → Active (shipped to main) → Superseded/Retargeted. Format in docs/prds/README.md.
  • Research notes (docs/research/) — opinionated investigations; unnumbered kebab-case, freeform and verdict-first. See docs/research/README.md.
  • Decision records (docs/decisions/) — ADR-lite, numbered NNNN-kebab.md, for policies and non-feature decisions. See docs/decisions/README.md.
• Keep decision rationale self-contained in the repo, not in Gitea issue threads. Issues are an ephemeral inbox; the durable "why" lives in a PRD, research note, or decision record.
• Low dependencies by default. The project is Python, stdlib-first (no runtime pip dependencies in the package itself; the only language runtime is the Python 3.13 used by the CLI + sidecars). Ask before adding new tools, runtimes, or package managers.
• Commit messages follow Conventional Commits: <type>[(scope)][!]: <description>, where <type> is one of feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. A commit-msg hook in .githooks/ enforces this. Activate it once per clone with git config core.hooksPath .githooks.

When you're unsure

Ask. Default to drafting in chat over editing files when the request is ambiguous.