AGENTS.md

Conventions

Use plain import and from statements in Python files.
Use the .py extension for Python source and test files.
tai.py is the entire product in one standalone stdlib-only file: CLI entry plus the stable import tai surface, grouped into classes (instance classes for stateful clusters, static utility classes for stateless groups). It must import nothing outside the standard library; a bare copy of the file has to import and run anywhere. Canonical patch targets are tai.<Class>.<name> (or the module attribute for module-level data).
There are two kinds of test, in two different places, on purpose — see "Testing" below for the full split. In short: unit tests are top-level test_*.py; integration tests are tests/<topic>.py (no test_ prefix) built on tai_test.py.
The in-tai.py TUI framework is documented in tui.md — read it before touching any Tui* code.
The terminal multiplexer (Mplex* classes, tai.py --mplex, ~/.tai/mplex.toml) is specified in mplex.md: read it before touching any Mplex* code, and keep its option, command and key tables in step with the code (MplexSpecTests fails when they drift).

Testing

Unit tests: test_tai.py, test_seal.py, at the repository top level, named test_*.py, unittest-based, import tai.py as a module directly, no subprocess, fast. python3 test_tai.py / python3 test_seal.py, or a single test via python3 -m unittest test_tai.SomeClass.test_method.

Integration tests: tests/<topic>.py (e.g. tests/rag.py), deliberately not named test_*.py and not at the top level, so the two kinds are never confused. These drive the real tai.py binary as a subprocess (one-shot or REPL) and check actual CLI behavior, using tai_test.py (the framework, at the repository root) as the one and only base to build on — never a one-off subprocess/asyncio harness per file. They must exercise a real LLM call through the real binary — never a mocked model or a database write standing in for what the agent would have done; the resulting flakiness from a free, rotating backend is accepted, not engineered away. Full conventions, that rule's full rationale, the required isolation rule (always a throwaway TAI_HOME), and why verification must check vault state rather than scrape CLI rendering, are in tests/README.md — read it before adding a new one. Run with python3 tests/<topic>.py (--filter, --interactive, --timeout all supported).

Agent Overview

tai: The main autonomous agent.
devops: A bot that manages the DevPlace DevOps platform.

Agent Profiles

default: Default agent profile for general tasks.
work: Work-focused agent profile.
dev: Development-focused agent profile.

Bot Details

devops: A bot that automates DevPlace DevOps operations.
- Manages workspaces, projects, and deployments.
- Handles user authentication and access control.
- Provides development tools and utilities.
- Integrates with OpenShift Dev Spaces.

Key Features

Autonomous decision making
Multi-profile support
Background subagent orchestration
Secure vault storage
Container sandbox support
Progress tracking
Interactive REPL
Command-line interface

Usage Examples

Start the main agent:
```
./tai.py
```
Use a specific profile:
```
./tai.py --profile work
```
Run a one-shot command:
```
./tai.py what is 2+3, use the shell
```
Check agent status:
```
./tai.py --version
```
Install the agent:
```
./tai.py --install
```

Development Guidelines

Write clear, concise code
Follow Python conventions
Test thoroughly
Use the agent for documentation
Keep code maintainable
Document decisions
Version control changes
Collaborate effectively

Command Output Rule

Every command an agent runs for the user (shell, ssh, sandbox box) must stream live to the user in both modes, in addition to being returned to the agent. It is a message, not a blocking spinner: a fixed-height window (REPL LiveStream, chat TUI live block) that keeps scrolling its last lines in place while the user keeps chatting. If the command stops on a prompt (sudo, ssh, y/n), it runs on a pty and asks the user through the same channel as ask_user (agent.prompter / REPL input); the answer is typed into the command, a decline sends end-of-file, and waiting for the user never counts against the timeout. Any new tool that runs a process must go through run_live with Tools.shell_stream and Tools.shell_ask, never a bare subprocess.run. Details: tui.md (chat scene).

Research Rule

All external research conducted for this project (web searches, reading documentation to settle a design question, competitive/prior-art analysis) is archived under research/, maintained under the auspices of the Molodetz Institute — Research & Retrieval Division. The full specification — folder layout, the three required document types (Source Dossier, Source Citation Card, Conclusion Document), required metadata, and the quality bar — lives in research/README.md; research/INDEX.md is the living registry and statistics page. Read research/README.md in full before writing into this archive.

The binding rule, in short: a research task is not done until it is written into research/. Every source actually consulted gets its own document (Tier 1 if read and synthesized, Tier 2 if only seen in a result listing — never skipped, never inflated past what's actually known), every decision the research produced gets its own Conclusion document in that subject's conclusions/ folder, and research/INDEX.md gets updated in the same pass. Check research/INDEX.md for an existing subject before opening a new one.

5.8 KiB Raw Permalink Blame History