Skip to content
Repos

blackcat

Markdown 12.2 KB225 lines Opens in site

Directory Raw Download

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 <retoor@molodetz.nl>, 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 <!-- doc: ... --> 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
    <!-- 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 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 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
342.8ms