# Agent instructions: blackcat Three layers, never merged: 1. Personal base rules (operator-owned, every project): the seriousdevelopment skill (user scope). Safety, proof, craft, ops. 2. This file (root project rules): applies to the whole repo. 3. Nested subsystem files (next to the code, loaded on touch): none yet. design.md is canonical for the TUI look and behavior. Every rule below is marked HARD RULE, CONVENTION, or GUIDANCE, with its enforcer. A rule without an enforcer is a wish. ## Project facts - blackcat is a Python agent harness: DeepSeek and OpenRouter live providers plus an offline echo provider. Entry points: the `blackcat` console script (blackcat.cli:main) and the library API (BlackCatBot in blackcat/agent.py). - Core package needs exactly two runtime dependencies: `aiohttp` (async HTTP transport) and `stealthii` (real-Chromium fetching). Textual is the only optional extra: pip install 'blackcat[tui]'. - Canonical docs: README.md (usage), design.md (TUI visual spec), CHANGELOG.md (version history), docs/DEFINITION_OF_DONE.md (delivery checklist), this file (agent rules). No orphan docs: every markdown file links to at least one other doc. ## Hard rules - HARD RULE: never edit the upstream prompt strings (TOOL_SCHEMAS descriptions, DSML_NUDGE, converge and extract prompts). They stay byte-identical to upstream. SYSTEM_DEFAULT is the one exception and is operator-owned: it ships here, is versioned here, and is pinned by `tests/test_system_prompt.py` (sections in order, every doctrine clause, no tool inventory, no repeated line, ASCII only, token cap). Change it only as a deliberate prompt change with that test updated in the same change, never as a drive-by edit. Appending guidance is allowed only in the wire-level tool text in _build_wire or in tool descriptions of tools added later. Enforcer: review of the diff for blackcat/agent.py prompt constants plus the prompt contract tests. - HARD RULE: every Python file in blackcat/ and tests/ carries exactly one comment line, the header `# retoor `, placed after the module docstring (when it has one) and any `from __future__` imports, before all other code. Docstrings are not comments and stay; `#` inside strings is fine. No commented-out code, no decision notes in the source. Enforcer: tokenize scan (every COMMENT token in the repo is the header line); the exact scan lives in docs/DEFINITION_OF_DONE.md §4. - HARD RULE: pathlib over os.path in package code. Sole exception: os.path.relpath (pathlib has no outside-root-tolerant equivalent). Enforcer: ruff PTH rules, `ruff check blackcat/ tests/` clean. - HARD RULE: annotations are PEP 585 and PEP 604 style (list[str], str | None). Python floor is 3.11; requires-python in pyproject.toml says so. Enforcer: ruff UP rules. - HARD RULE: tests are stdlib unittest, offline, no network. Never narrow, skip, or weaken a failing test to make a run pass; fix the code or state plainly why the test expectation is wrong. TUI tests skip only through the HAS_TEXTUAL guard. Enforcer: full suite run. - HARD RULE: version lives in exactly one place: pyproject.toml. blackcat.__version__ reads it live; never hardcode a version string anywhere else. Every change bumps the patch version (minor for scope changes, major for breaking changes) and adds one ascending row to CHANGELOG.md in the same change. Edited markdown docs bump their `` header version and date in the same change. Enforcer: `python -m blackcat --version` output equals the pyproject.toml version. - HARD RULE: never stage, commit, push, tag, or rewrite git history unless the user asks for that exact action in the current session. Leave work in the working tree for review. Enforcer: git status shows the work unstaged at handoff. - HARD RULE: never print, copy, or commit secret values (.env, API keys). Referencing an env var name to wire config is fine. Enforcer: diff review; .env stays gitignored. - HARD RULE: no em-dashes in prose, docs, commit messages, or chat. Use hyphens. Enforcer: `grep -rn $'\u2014' --include='*.md' .` over changed docs prints nothing. - HARD RULE: the file-tool sandbox and approval model stay intact unless the user asks to change them. --yolo is the only bypass: it skips tool_confirm and lifts root confinement; read-before-write and staleness guards always apply. Enforcer: tests in tests/test_tools.py, tests/test_agent_tools.py, tests/test_tui.py. - HARD RULE: all execution is asyncio end to end and stays cancellation-correct under Ctrl+C. Blocking work never runs on the event loop; CancelledError/KeyboardInterrupt is caught only to convert into a user-cancelled tool result (with settle() when the result is kept) or to clean up process groups before re-raising. One press cancels the running tool and the turn continues; three quick presses abort the turn back to input; the message history never dangles without its tool answers. Enforcer: tests/test_cancel.py passes plus review of every new except around an await. - HARD RULE: package code is object-oriented everywhere, not just in tui/. No module-level mutable state and no module-level logic functions in blackcat/ or tests/; shared tables, flags, and session state live on classes. Module-level names are read-only constants, aliases, or thin delegates. Every widget that starts a timer stops it in on_unmount. Enforcer: review of the diff. - HARD RULE: no orphan docs. Every markdown file links to at least one other doc; new docs are linked from the README table and the canonical list in this file. Edited markdown docs bump their `` header version and date in the same change. Enforcer: link audit in docs/DEFINITION_OF_DONE.md §9. ## Conventions - CONVENTION: implementation logic lives in the core modules (agent.py, tools.py, fstate.py, client.py). The TUI only renders: it talks to the bot through TUIBot UIEvents in blackcat/tui/bridge.py and never grows core behavior of its own. - CONVENTION: DRY and consistent. One implementation per behavior: reuse the existing helper instead of adding a parallel one, match sibling API shapes (same types, keys, constructors, ok/code error fields), and add no unrequested interfaces, files, or options. Enforcer: review of the diff against the touched area's siblings and call sites. - CONVENTION: new tools register in TOOL_SCHEMAS, dispatch in run_tool, keep result dicts JSON-shaped with ok/code fields, and get a TUI card (generic card at minimum) plus tests. - CONVENTION: long-task support is harness-side: model-aware context limits, tiered compaction, the todo tool, and --session resume. Prefer improving those over prompt wording. - CONVENTION: logging is stdlib logging, configured once in blackcat/cli.py setup_logging; lazy percent-formatting in log calls; progress on stderr, results on stdout. - CONVENTION: research before load-bearing decisions (vendors, stack, formats): search the web, then record the decision and its rationale in CHANGELOG.md or this file. ## TUI quality rules (Textual best practices) Researched 2026-11-08: the python-cli-toolcraft Textual guide (structure apps like a web front end, keep logic out of widgets, never block the event loop, test with run_test and Pilot) and the Textual community references (attributes down with reactive state, messages up with Message and on_* handlers, async work in workers, TCSS for layout). These rules constrain blackcat/tui/ only. - HARD RULE: the tui/ package is object-oriented. No module-level mutable state and no module-level logic functions. Shared tables and flags live on classes (GlyphSet, CardStyle, CardText, CardFactory, Gradient, Thumbnail, GitInfo, TuiLauncher); module-level names are read-only aliases or thin delegates kept for backward compatibility. Enforcer: review of the tui/ diff. - HARD RULE: every widget that starts a timer stops it in on_unmount. Enforcer: grep for set_interval without a matching stop in the same class. - CONVENTION: state lives in reactive() attributes with watch_ responders (and validate_ coercion where input is untrusted); never assign-then-manually-refresh from scattered handlers. - CONVENTION: blocking work runs in @work(thread=True) workers. Workers never touch widgets; they post results back with call_from_thread. - CONVENTION: cross-widget communication uses Message subclasses and on_* handlers. The app never reaches into card internals except through the card's own methods. - CONVENTION: every visual decision lives in blackcat.tcss. Python code carries behavior only. - CONVENTION: card bodies cap overflow with ToolCard.mount_capped. Animations are objects (CountUp), not closures over widget state. - CONVENTION: every card is sealed by ToolCard.seal() after mount and after done (RenderContract in blackcat/tui/quality.py): no render path may end with an empty header or an empty displayed body. Content exists from construction: the header carries real text and the body carries a status row from __init__, so even a crashing on_mount cannot leave a blank box. The status row is only ever shown or hidden via the synchronous display flag; Widget.remove() applies on the message pump while mount() and flag writes are synchronous, so remove() is banned from the seal path and finish() re-seals on a short settle timer. Tests assert only after settling, never right after a status flip. - CONVENTION: the Transcript audits every card against the contract once per second (Transcript.audit_cards) and re-seals violators; the timer stops in on_unmount like every other timer. - HARD RULE: screen-mounted overlay effects (cost rain, confetti) live on the toast layer, never in flow: even absolute-positioned screen children steal 1fr space. Animate offset through Widget.animate with geometry.Offset (styles.animate cannot blend offsets and raises AnimationError); animate opacity through styles.animate. Schedule the removal timer before starting animations so a failed animation can never leak a widget. Enforcer: layout-stability tests assert middle height and prompt-row position across effects and collapse. - HARD RULE: animation frames never re-lay-out. Per-tick text updates use `layout=False`; exactly one render runs per tick (never a watcher render plus a direct render). Enforcer: the tick benchmark in the 0.3.8 notes (5.6ms down to 1.1ms per card-tick) plus review of every `set_interval` callback. - HARD RULE: cards size to content (`.tool-card` is `height: auto` with `min-height`). Never let a card flex (`1fr` made cards absorb free space and clip their text under `overflow: hidden`, painting empty boxes). Enforcer: the paint-level test (`TestPaintContract`) asserts card text in a real SVG screenshot. - CONVENTION: Textual imports stay lazy behind blackcat.tui so the core package needs nothing beyond aiohttp and stealthii. - CONVENTION: interactions get Pilot tests; pure formatting and registry logic gets plain unit tests with no app running. ## Definition of done (automatic, every task) A task is done only when every check in [docs/DEFINITION_OF_DONE.md](docs/DEFINITION_OF_DONE.md) holds. No exceptions, no narrowing to get green. In short: the request is implemented exactly as asked with its edge cases; focused tests exist and pass; the full suite passes in this session (`.venv/bin/python -m unittest discover -s tests`, TUI tests take most of the runtime and skip cleanly without the tui extra); `ruff check blackcat/ tests/` is clean; touched docs are updated and their headers bumped; the retoor header is the only comment and asyncio stays cancellation-correct; package code stays object-oriented, DRY, and consistent; pyproject.toml is bumped with one ascending CHANGELOG.md row; the tree is left uncommitted; and the final report states what was verified by running it and what was not, naming any unverified part plainly. ## Commands - Test: `.venv/bin/python -m unittest discover -s tests` - Lint: `.venv/bin/ruff check blackcat/ tests/` - Run: `.venv/bin/python -m blackcat --provider echo prompt "hi"` - TUI: `.venv/bin/python -m blackcat --provider echo tui` - Version check: `.venv/bin/python -m blackcat --version`