Skip to content

Commit 265efd5

Browse files
committed
docs: add system analysis reports and planning docs
Includes full-system critical review, competitive landscape, architecture critique, risk/trust model analysis, multi-agent coordination evaluation, and improvement work directions. Also updates docs INDEX and validation script. Constraint: no source code changes Tested: git diff shows only docs/ and scripts/ changes Confidence: high
1 parent ad5e2d7 commit 265efd5

14 files changed

Lines changed: 3621 additions & 6 deletions

docs/INDEX.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# TeaAgent Documentation Index
2-
# 2026-06-05
2+
# 2026-06-06
33

44
This is the curated front door for TeaAgent documentation. It is intentionally
55
not an exhaustive file list. Use it to find the current source of truth, then
@@ -47,6 +47,13 @@ follow dated evidence documents only when you need the reasoning trail.
4747
| Seven control loops product direction | [Seven Control Loops Product Direction](strategy/seven-control-loops-product-direction-2026-06-05.md) |
4848
| Seven control loops critical questioning | [Seven Control Loops Critical Questioning](reviews/seven-control-loops-critical-questioning-2026-06-05.md) |
4949
| Community agent pain points | [Community Agent Pain Points Survey](analysis/community-agent-pain-points-survey-2026-06-05.md) |
50+
| June 6 system critical review package | [System Critical Review Package](analysis/system-critical-review-2026-06-06-INDEX.md) |
51+
| June 6 source-backed competitor self-comparison | [Competitor Self-Comparison Matrix](analysis/competitor-self-comparison-matrix-2026-06-06.md) |
52+
| June 6 public reasoning ledger | [System Review Reasoning Ledger](analysis/system-review-reasoning-ledger-2026-06-06.md) |
53+
| June 6 engineering architecture critique | [Engineering Architecture Critique](analysis/engineering-architecture-critique-2026-06-06.md) |
54+
| June 6 multi-agent coordination critique | [Multi-Agent Coordination Critique](analysis/multi-agent-coordination-critique-2026-06-06.md) |
55+
| June 6 conversation UX analysis | [User Experience And Conversation Patterns](analysis/user-experience-and-conversation-patterns-2026-06-06.md) |
56+
| June 6 risk and trust model critique | [Risk And Trust Model Critique](analysis/risk-and-trust-model-critique-2026-06-06.md) |
5057
| Phase 0-to-1 outlook | [Phase 0 To Phase 1 Outlook](strategy/phase-0-to-phase-1-outlook-2026-06-04.md) |
5158
| Malleable governed agent harness | [Malleable Governed Agent Harness](strategy/malleable-governed-agent-harness-2026-06-03.md) |
5259
| Daily-driver roadmap rationale | [Daily-Driver Roadmap Rationale](strategy/daily-driver-roadmap-rationale-2026-06-04.md) |
@@ -95,6 +102,7 @@ follow dated evidence documents only when you need the reasoning trail.
95102
| [Seven Control Loops Work Items](plans/seven-control-loops-work-items-2026-06-05.md) | Cross-cutting task ledger for spec-first, dynamic workflow, goal loops, model routing, review, memory, and human gates. |
96103
| [Seven Control Loops Integration Map](architecture/seven-control-loops-teaagent-integration-map-2026-06-05.md) | Architecture map for integrating the seven control loops into existing TeaAgent surfaces. |
97104
| [Community Pain Points Response Plan](plans/community-pain-points-response-plan-2026-06-05.md) | Work plan for routing opacity, memory pollution, review cost, long-task drift, hook confusion, skill/MCP risk, and fake success. |
105+
| [System Improvement Work Directions](plans/system-improvement-work-directions-2026-06-06.md) | 2026-06-06 workstream and ticket decomposition for trust claims, conversation UX, multi-agent safety, observability, integration contracts, docs governance, and competitive positioning. |
98106

99107
### Historical Reference Plans
100108

docs/analysis/competitive-landscape-and-positioning-2026-06-06.md

Lines changed: 327 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Competitor Self-Comparison Matrix — TeaAgent
2+
# 2026-06-06
3+
4+
> **Status:** Source-backed point-in-time comparison.
5+
> **Scope:** Selected direct and adjacent AI coding-agent competitors whose
6+
> official documentation or upstream pages were checked on 2026-06-06.
7+
>
8+
> This is not a claim to cover every coding assistant in the market. It covers
9+
> the competitors most relevant to TeaAgent's current product thesis: terminal
10+
> agents, IDE agents, remote/cloud coding agents, and governed orchestration
11+
> systems.
12+
13+
---
14+
15+
## Source Map
16+
17+
Official or upstream sources used for this matrix:
18+
19+
- OpenAI Codex help: <https://help.openai.com/en/articles/11369540-getting-started-with-codex>
20+
- OpenAI Codex upgrades: <https://openai.com/index/introducing-upgrades-to-codex/>
21+
- OpenAI Codex broader app/workflow positioning: <https://openai.com/index/codex-for-almost-everything/>
22+
- Anthropic Claude Code extension overview: <https://code.claude.com/docs/en/features-overview>
23+
- Anthropic Claude Code subagents: <https://code.claude.com/docs/en/sub-agents>
24+
- GitHub Copilot cloud agent: <https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent>
25+
- GitHub Copilot session entry points: <https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions>
26+
- GitHub Copilot model policy: <https://docs.github.com/en/copilot/concepts/models/fallback-and-lts-models>
27+
- OpenCode agents and permissions: <https://opencode.ai/docs/agents/>
28+
- Aider usage and git integration: <https://aider.chat/docs/usage.html>, <https://aider.chat/docs/git.html>
29+
- Cline overview and Plan/Act: <https://docs.cline.bot/cline-overview>, <https://docs.cline.bot/core-workflows/plan-and-act>
30+
- Cursor background agents and API: <https://docs.cursor.com/background-agent>, <https://docs.cursor.com/background-agent/api/overview>
31+
- Cursor modes, permissions, and rules: <https://docs.cursor.com/agent>, <https://docs.cursor.com/cli/reference/permissions>, <https://docs.cursor.com/context/rules-for-ai>
32+
- Kiro autonomous mode, specs, steering, hooks, web, and CLI: <https://kiro.dev/docs/web/autonomous-mode/>, <https://kiro.dev/docs/specs/>, <https://kiro.dev/docs/steering/>, <https://kiro.dev/docs/cli/hooks/>, <https://kiro.dev/docs/web/>, <https://kiro.dev/docs/cli/>
33+
- Devin introduction and release notes: <https://docs.devin.ai/get-started/devin-intro>, <https://docs.devin.ai/release-notes/2026>
34+
- OpenHands sandbox overview: <https://docs.openhands.dev/openhands/usage/sandboxes/overview>
35+
- Google Jules docs and product page: <https://jules.google/docs/>, <https://jules.google/>
36+
- Windsurf/Cascade docs: <https://docs.windsurf.com/windsurf/accounts/usage>, <https://docs.windsurf.com/plugins/cascade/models>, <https://docs.windsurf.com/windsurf/cascade/workflows>, <https://docs.windsurf.com/windsurf/terminal>
37+
- Roo Code docs and shutdown notice: <https://docs.roocode.com/>, <https://roocodeinc.github.io/Roo-Code/basic-usage/using-modes/>, <https://roocodeinc.github.io/Roo-Code/advanced-usage/available-tools/tool-use-overview/>
38+
39+
Local TeaAgent evidence:
40+
41+
- `pyproject.toml` — alpha status, version, extras, scripts.
42+
- `teaagent/runner/_core.py` — run loop, budget checks, approval handling.
43+
- `teaagent/tools.py` — tool registry contract.
44+
- `teaagent/audit.py`, `teaagent/audit_chain.py` — audit log, hash chain, sinks, verification.
45+
- `teaagent/approval_manager.py`, `teaagent/policy.py`, `teaagent/read_only_gate.py` — permission and approval model.
46+
- `teaagent/subagents/*`, `teaagent/swarm.py` — local subagent and swarm orchestration.
47+
- `teaagent/tui/*`, `teaagent/chat_session_controller.py` — interactive conversation surface.
48+
49+
---
50+
51+
## Competitor Matrix
52+
53+
| Competitor | Confirmed Public Shape | Advantage Over TeaAgent | TeaAgent Advantage | Work Direction |
54+
| --- | --- | --- | --- | --- |
55+
| OpenAI Codex | Agent available across ChatGPT plans; CLI/IDE/cloud/GitHub review surfaces; compliance API coverage for Codex usage; cloud tasks can set up environments, use browser feedback, and review PRs. | Much stronger hosted/cloud, IDE, mobile, and GitHub review integration. Stronger public adoption and first-party model/channel integration. | TeaAgent is provider-agnostic and local-first; governance primitives are repo-native and inspectable. | Treat Codex as the benchmark for async task handoff, browser-backed frontend iteration, compliance log surface, and PR review UX. |
56+
| Claude Code | Strong extension model: CLAUDE.md, skills, subagents, agent teams, hooks, MCP, plugins, code intelligence, permission modes. | Richer mature agent ecosystem and clearer feature taxonomy; subagents and teams are better explained as distinct patterns. | TeaAgent's audit chain, budget caps, and policy/governance framing are more explicit in the repo. | Copy the taxonomy clarity, not the product wholesale: split TeaAgent docs into always-on context, skills, hooks, subagents, teams, MCP, and enforcement. |
57+
| GitHub Copilot cloud agent | Autonomous background work in GitHub Actions-powered environments; creates plans, branches, and PRs; many entry points including issues, IDEs, REST API, CLI, Slack, Teams, Jira, Linear, and MCP. | Distribution through GitHub and PR-native workflow is extremely strong. | TeaAgent can run outside GitHub and across providers, with local audit and stricter cost/permission controls. | Do not compete head-on on distribution; build GitHub/PR adapters that preserve TeaAgent governance and audit exports. |
58+
| OpenCode | Terminal-native agent with configurable agents, subagents, and fine-grained permissions for read/edit/bash/task/web/lsp/skill/question and wildcard patterns. | Strong terminal UX and an increasingly mature permission model; likely faster community iteration. | TeaAgent has broader governance/audit/cost/compliance ambitions and a fuller policy vocabulary. | OpenCode is the closest terminal threat. TeaAgent must make governance visible and useful, not just implemented. |
59+
| Aider | Terminal pair programmer; file-scoped context, multi-provider support, diffs, automatic git commits, and `/undo`. | Simpler mental model and excellent git-native reversibility. | TeaAgent handles richer tool governance, audit, approvals, budget, MCP, and multi-agent experiments. | Borrow the simplicity: make "what files will change" and "how to undo" obvious at every step. |
60+
| Cline | Editor and terminal agent; explicit approval per action; Plan/Act separation; SDK, CLI, Kanban, VS Code, JetBrains, checkpoints, browser, MCP, and enterprise controls. | Better daily developer fit through IDE and clear Plan/Act UX; actions are visibly approved. | TeaAgent has more explicit run evidence and local governance depth. | Make TeaAgent's plan-before-write path feel as simple as Plan/Act, with readable approvals and checkpoint receipts. |
61+
| Cursor | IDE agent modes, background agents in isolated remote machines, web/mobile agent entry points, API for background agents, and explicit CLI permissions. | Strongest IDE and async-background-agent UX among the selected tools; remote environment setup is productized. | TeaAgent has no equivalent hosted async agent but has stronger local audit/control primitives. | Treat Cursor as the remote-agent UX target. Do not enable remote multi-agent until isolation, queues, budgets, and progress are durable. |
62+
| Kiro | Spec-driven development, steering files, hooks, CLI, web preview, autonomous mode that clarifies, plans, delegates to subagents, and opens PRs from an isolated sandbox. | Strong requirements/spec/task workflow and remote autonomous loop. | TeaAgent has similar planning/governance instincts but less polished artifact flow. | Build TeaAgent's work-direction docs into machine-checkable spec/task/run evidence rather than more prose. |
63+
| Devin | Conversational web product with embedded IDE, terminal, browser, API, Slack/Teams handoff, CLI-to-cloud handoff, enterprise usage controls, MCP audit logs, and session ACU hard caps. | Most mature "AI teammate" collaboration surface and enterprise-facing admin/usage controls. | TeaAgent is open/local/provider-agnostic and cheaper to adapt internally. | Use Devin as the enterprise UX benchmark: session links, takeover, usage hard caps, enterprise audit events, and team review flow. |
64+
| OpenHands | Open-source agent platform with Docker sandbox recommended, process sandbox marked unsafe, and remote sandbox for managed deployments. | Stronger sandbox-first operating model and clearer isolation vocabulary. | TeaAgent has a broader governance layer but weaker integration of sandboxing into the primary tool path. | Rename weak isolation honestly and make worktree/container isolation the default for multi-agent writes. |
65+
| Google Jules | Experimental autonomous coding agent integrated with GitHub; works autonomously on bugs, docs, and features; hosted/cloud VM positioning. | Lower-friction hosted async task flow. | TeaAgent is more configurable and inspectable. | Use Jules as a reminder that "experimental" can still be simple to try; reduce TeaAgent's first-run ceremony. |
66+
| Windsurf / Cascade | IDE-centric Cascade with in-house SWE models, workflows stored as markdown, web/docs search, terminal integration, usage analytics, and usage-based plans. | Strong IDE workflow packaging and model/product integration. | TeaAgent is not bound to one IDE or model family. | Convert TeaAgent workflows and skills into compact, discoverable, repo-native artifacts with visible runtime receipts. |
67+
| Roo Code | Open-source VS Code agent with modes, custom modes, tool groups, MCP, and powerful customization; official docs now indicate shutdown of Roo Code products on May 15, 2026. | Historical strength in custom modes and mode-specific tool access; less current market threat after shutdown notice. | TeaAgent remains active in this workspace and can learn from Roo's mode system without inheriting its product risk. | Classify Roo as a design reference, not a primary strategic threat, unless a successor fork regains traction. |
68+
69+
---
70+
71+
## Cross-Competitor Pattern Comparison
72+
73+
| Pattern | Market Direction | TeaAgent Current Position | Implication |
74+
| --- | --- | --- | --- |
75+
| Remote async agents | Codex, Copilot, Cursor, Kiro, Devin, Jules all move work into isolated cloud or hosted environments. | Local-first; remote/server paths exist mostly as docs or partial surfaces. | Keep local-first as a principle, but do not market remote multi-agent until durable queues, budgets, and isolation exist. |
76+
| IDE-native UX | Cursor, Windsurf, Cline, Copilot, Kiro, Devin all reduce friction by living inside editors or PRs. | CLI/TUI first; VS Code/MCP exists but is not the main onboarding path. | The terminal can remain the power-user surface, but daily adoption needs editor/PR receipts. |
77+
| Plan/spec before write | Cline Plan/Act, Kiro specs, Claude planning/subagents, OpenCode permissioned agents all encode planning separation. | TeaAgent has plan-before-write enforcement, but the UX is less legible. | Keep enforcement; add readable plan receipts, file targets, tests, and approval diffs. |
78+
| Tool permissions | OpenCode, Cline, Cursor, Kiro, Roo, Claude all expose permissions or hooks. | TeaAgent has strong policy internals. | The differentiator must move from "we have permissions" to "we can prove every action, cost, and approval." |
79+
| Multi-agent orchestration | Claude agent teams, Kiro autonomous subagents, Cursor background agent API, Cline Kanban, Codex parallel agents. | Subagent and swarm layers exist but are local/in-process and partially divergent. | Unify orchestration before scaling it. Remote multi-agent without durable state is a credibility risk. |
80+
| Audit/compliance | Codex has Compliance API; Devin has enterprise audit logs; GitHub has PR/session logs. | TeaAgent has hash-chained audit and signed/exportable run records. | This is TeaAgent's best strategic lane. It should become the primary product story. |
81+
| Cost caps and usage visibility | Devin release notes mention session ACU hard caps; GitHub/Windsurf/Codex have usage surfaces; many tools still rely on plan billing. | TeaAgent has hard estimated-cost caps but cost estimation can be inaccurate by provider. | Make cost state honest: actual, estimated, unavailable, or local-provider non-billable. |
82+
83+
---
84+
85+
## Strategic Positioning
86+
87+
TeaAgent should not position itself as the fastest IDE agent or the most polished
88+
hosted teammate. Competitors already own those lanes. TeaAgent's credible lane is:
89+
90+
> A local-first, provider-agnostic governance harness for agentic coding work,
91+
> designed to make every model decision, tool call, approval, cost estimate,
92+
> file write, and recovery path auditable.
93+
94+
This positioning is narrow but defensible. It appeals to:
95+
96+
- Security-conscious engineering teams.
97+
- Platform engineers running agents in CI or controlled workspaces.
98+
- Regulated or compliance-sensitive environments that need evidence, not just
99+
productivity claims.
100+
- Power users who want multi-provider flexibility without surrendering audit
101+
and approval control.
102+
103+
It does not appeal first to:
104+
105+
- Beginners who want an IDE-first assistant.
106+
- Teams that want hosted async PRs today.
107+
- Users who value speed over governance.
108+
- Organizations requiring multi-tenant SaaS, SOC 2 evidence, SSO/RBAC, and a
109+
polished admin dashboard immediately.
110+
111+
---
112+
113+
## Competitive Risks
114+
115+
| Risk | Why It Matters | Mitigation |
116+
| --- | --- | --- |
117+
| OpenCode closes the permission gap. | It is closest to TeaAgent's terminal lane and already documents fine-grained permissions. | Move up-stack into audit, cost, compliance export, and evidence receipts. |
118+
| Claude Code normalizes skills/subagents/hooks taxonomy. | Users may expect Claude's vocabulary everywhere. | Align TeaAgent docs with the same conceptual distinctions while preserving local semantics. |
119+
| GitHub/Codex/Cursor own async work. | Remote PR workflows become the default expectation for "agent." | Make local governance + PR adapter the wedge; defer hosted until local safety is strong. |
120+
| TeaAgent overclaims alpha/beta features. | Competitors are polished enough that doc drift will be punished quickly. | Add freshness labels, claim classes, and CI docs consistency guards. |
121+
| Governance is a niche, not a mass-market hook. | Most developers may choose speed. | Aim for regulated, security, platform, and CI personas first. |
122+
123+
---
124+
125+
## Claims Not Made
126+
127+
- No exact GitHub star ranking is asserted in this file.
128+
- No pricing comparison is asserted beyond official usage/cost-control shapes.
129+
- No benchmark quality ranking is asserted.
130+
- No claim is made that TeaAgent is enterprise-ready today.
131+
- No claim is made that the selected competitor set is exhaustive.

0 commit comments

Comments
 (0)