History Architecture

Architecture

TeamCLI (team) runs a team of AI agents for a software project. Its purpose is a team across labs: different vendors can supply the agents best suited to implementation, review, coordination, and other roles. One lab can also supply every seat. A project may include code and supporting repositories such as docs, site, and infrastructure; coordinated multi-repository work is planned, not built.

The team file

.agents/team.yaml declares the team: its seats and roles, the CLI and model each seat runs, its rules and work signature, and the folders it may touch. The file is private to a clone. TeamCLI validates it, records the version the owner agreed to on that machine, and checks that agreement before acting on protected settings. Today, folder scope and rules guide agents but are not operating-system containment.

Commands

Command	Purpose
team init	Write a starter team file.
team approve	Show and record the owner's agreement to the file.
team up	Start the declared team and its seats.
team down	Stop the team.
team status	Compare declared seats with the running session and show differences.
team add <name>	Start one allowed seat.
team remove <name>	Stop or remove one seat.
team watch	Observe idle or stuck seats and report waiting work.
team doctor	Check the machine, CLIs, logins, and launch setup.
team usage	Report recorded account usage across teams.
team commits check / team pr check	Check commit and pull-request text against signature and forbidden-pattern rules.
team answer <seat> trust	Answer a narrowly recognized folder-trust prompt when policy allows it.
team worktree new / team worktree remove	Manage a task worktree.
team release check	Read public release records and compare the declared release.

Generic core, adapter edge

• Agent harness. The shared team model defines seats, lifecycle, agreement, status, and checks. CLI-specific profiles handle how each vendor's agent starts, what its screen means, and how it receives rules. This is partly built; automatic recovery and a complete shared work lifecycle are planned.
• Planning (draft RFC 008). A generic task record and pull policy would let seats take work from a declared source. Each tracker gets an adapter; a broker would mediate credentials and disclose only allowed fields. No task source, broker, lease, or team next exists today.
• Roles and skills (draft RFC 009). Reusable roles would define constraints; reusable skills would describe how to perform allowed work. Project and task bindings would select them. A harness adapter would deliver each binding to a vendor CLI and report when delivery fails. Today, roles and rules are written inline in each team file; the libraries and bindings are planned.
• Repositories (Foundation revision proposal). A project would declare one or several repositories, with seats scoped to each. Repository or forge specifics belong at the adapter edge. Cross-repository work would be coordinated changes, checked and accepted per repository; atomic cross-repository merges are not promised. Multi-repository support is planned.

Security boundary

The current checks help prevent a mistaken agent from running commands or using a team file outside its agreement. They do not contain a hostile agent running as the same operating-system user: it may read files and keys that user can read. Owner detection from process placement can also be forged by a hostile same-user process. The proposed planning broker has the same-principal limit: a local socket and separate credential holder do not isolate a hostile seat if both run under the same OS principal. Stronger isolation requires a separate principal or sandbox. No current TeamCLI protection is claimed to hold against a deliberate attempt.

The RFC series

The public RFCs state commitments and, separately, what the released tool actually does. RFCs 000–007 are accepted; 008 and 009 remain drafts, as does the proposed Foundation revision.

RFC	Scope
000 Foundation	Principles, the life of a team and its work, and how commitments are decided.
001 Security	Authority, agreements, limits, and the protection each check really provides.
002 Communication	Delivery, identity, and visibility of messages among agents and people.
003 Memory	Shared knowledge across agents and sessions, with control over what persists.
004 Analysis	Evidence-based findings about projects, teams, and work.
005 Quality	Definitions of done, review policy, and what a check establishes.
006 Consensus	Rules and evidence for decisions made from several voices.
007 Harness	Starting, observing, and keeping a team running across CLIs.
008 Planning (draft)	Tracker-agnostic backlog access, task pulling, and scheduling.
009 Roles & Skills (draft)	Versioned role and skill libraries with project and task bindings.