Agent instructions: blackcat
Three layers, never merged:
- Personal base rules (operator-owned, every project): the
seriousdevelopment skill (user scope). Safety, proof, craft, ops. - This file (root project rules): applies to the whole repo.
- 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
blackcatconsole script (blackcat.cli:main) and the library API
(BlackCatBot in blackcat/agent.py). - Core package needs exactly two runtime dependencies:
aiohttp
(async HTTP transport) andstealthii(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
bytests/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 <retoor@molodetz.nl>, placed after the module docstring (when it
has one) and anyfrom __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<!-- doc: ... -->header version and date in the
same change. Enforcer:python -m blackcat --versionoutput
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
<!-- doc: ... -->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 uselayout=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 everyset_intervalcallback. - HARD RULE: cards size to content (
.tool-cardis
height: autowithmin-height). Never let a card flex
(1frmade 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 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