Skip to content

Contributing to TeaParty

TeaParty is a research platform for durable, scalable agent coordination. We are building toward a future where teams of humans and AI agents work together on increasingly difficult projects. The platform eats its own dogfood: the documentation, design artifacts, and implementation are produced by hierarchical agent teams running the TeaParty POC.

How We Work

Use TeaParty to Build TeaParty

Wherever possible, use the TeaParty orchestrator to implement new features. This is not a suggestion — it is the primary way the platform gets tested and improved. Every session produces learnings that feed back into the system. If a task can be expressed as a natural-language request to the orchestrator, it should be.

uv run python -m projects.POC.orchestrator "Your task description"

When the orchestrator cannot handle a task (tooling gaps, permission issues, tasks that require human judgment throughout), work directly — but note what the orchestrator could not do and why. Those observations are research data.

Branching Strategy

We follow gitflow:

  • main — latest stable release. Squash-merged from develop with a descriptive commit message. Never commit directly to main.
  • develop — integration branch. Feature work merges here first. All tests must pass.
  • fix/issue-<number> or feature/<name> — working branches. One branch per issue. Branch from develop, merge back to develop.

Always Be Running

main and develop must always be in a working state. Tests pass, docs build, the system runs. This is non-negotiable. If you merge something that breaks develop, fixing it is your top priority — above whatever you were working on.

Feature branches are where things break. Experiment freely, commit broken intermediate states, push work-in-progress. That is what branches are for. But before you open a PR to develop, rebase on develop and verify that tests pass and docs build. CI enforces this — PRs that fail checks cannot merge.

Pull Requests and Human Approval

No work merges to develop or main without a pull request and human approval. This is not negotiable. Agent-produced code, documentation, and design changes all require human review before integration. The PR description should explain what changed and why.

PRs to develop require a rebase on develop before merging (linear history is enforced). PRs to main are squash-merged — the PR description becomes the commit message on main, so write it like a release note.

Worktrees

Each issue gets its own git worktree. This provides process-level isolation — concurrent work on different issues does not interfere.

git worktree add ../teaparty-fix-<number> -b fix/issue-<number> develop

Subteam dispatches within a session create child worktrees branched from the parent session's worktree. Completed work is squash-merged back up.

Coding Standards

Philosophy

  • Conceptual clarity always. If you cannot explain what the code does in plain language, it is not ready.
  • Agents are agents — autonomous, not scripted. No prescriptive prompts, no retry loops for tool use. Agent output is never truncated.
  • Workflows are advisory, not mandatory — agents follow them by choice, not enforcement.
  • No over-engineering. Only make changes that are directly requested or clearly necessary. Three similar lines of code is better than a premature abstraction.
  • No silent fallbacks. Silent fallbacks are errors. They give the illusion code is working when it is not. If a component fails, the failure must be visible.
  • No historical artifacts. No dead code, no stale docs, no historical comments. That is what git history is for. If something is no longer accurate or relevant, delete it.

Python

  • The active codebase is projects/POC/orchestrator/.
  • All agent invocations go through claude -p (Claude Code CLI in pipe mode).
  • Use best-in-class libraries over bespoke code. Never defend hand-rolled implementations just because they work.

Tests

  • unittest.TestCase with _make_*() factory helpers. Not pytest fixtures. No conftest.py.
  • Tests live in projects/POC/orchestrator/tests/.
  • Write failing tests first, then fix. Every bug fix commit should include a test that would have caught it.
uv run pytest projects/POC/orchestrator/tests/ --tb=short -q

Documentation

Documentation follows an academic paper structure. The mkdocs site (uv run mkdocs serve) is the authoritative rendered form.

Section Purpose Directory
Introduction What TeaParty is, the problem, contributions docs/index.md, docs/overview.md
Architecture The six systems (CfA, Messaging, Workspace, Human Proxy, Learning, Bridge) docs/systems/
Case Study End-to-end demonstration of the system docs/case-study/
Research Academic context, vanilla technology references (ACT-R, Soar), narrative essays docs/research/
Guides How-to content (project onboarding, etc.) docs/guides/
Reference Folder structure, team configuration, built-in teams, dashboard, UX, autodiscovery docs/reference/
Evaluation Experimental results and ablations docs/experimental-results/
Future Work Proposals docs/proposals/

Each system folder has a progressive index.md. Concepts, mechanism, status, and links to deeper topics in one page. Detail lives in sibling files within the same folder. See docs/systems/cfa-orchestration/index.md for the shape.

Research essays are narratives, not bullet-point lists. They tell a story: here is the intellectual landscape, here is what exists, here is the gap we address. The docs/research/ folder contains both our own positioning essays and vanilla technology references (ACT-R, Soar, etc.) that we build on.

Proposals are intellectually honest. If a design is not implemented, it lives in docs/proposals/. Implemented designs belong in docs/systems/ with an honest status section that distinguishes operational from in-progress.

Commit Messages

Line 1: Issue #<number>: <short description> (or a descriptive summary if no issue). Remaining lines: describe the work in detail — what changed and why.

Tools and Skills

The .claude/ directory contains skills and agent definitions that automate common workflows:

  • /audit — multidimensional code review with parallel subagent reviewers
  • /refine — dialectical refinement of design documents
  • /fix-issue <number> — systematic issue investigation and resolution
  • /research <topic> — deep academic and technical research

These skills use subagent isolation to prevent context window exhaustion. Each reviewer or role runs in its own context window, communicating through the filesystem.

CI

CI runs automatically on PRs to main and develop. Both jobs must pass before a PR can merge:

  • test — runs uv run pytest tests/
  • docs — runs uv run mkdocs build

These cover the deterministic layer: state machine logic, activation math, dispatch, learning extraction, proxy memory, and doc cross-references. The agentic layer (LLM calls, approval gate decisions, session behavior) is non-deterministic and cannot be tested in CI — that is what dogfooding sessions are for.

Getting Started

git clone https://github.com/dlewissandy/teaparty.git
cd teaparty
uv sync
uv run pytest tests/ --tb=short -q                               # verify tests pass
uv run mkdocs serve                                              # browse docs at localhost:8000

To run a session interactively (requires Claude Code CLI and a human at the approval gates):

./teaparty.sh                                                    # HTML dashboard (localhost:8081)
uv run python -m teaparty "Your task"                            # CLI session

Read docs/index.md for the research overview, then docs/overview.md for the organizational model, then docs/systems/index.md for the architecture. The narrative essays in docs/research/ provide the intellectual context.