slopus--happy/docs/competition/AGENTS.md

Competition Research

Use this folder for distilled competitor research that is worth keeping in the Happy repo.

What belongs here

• markdown notes about how another product works
• protocol writeups, message samples, and sequence diagrams
• screenshots and small sanitized artifacts that explain behavior
• links to upstream docs, repos, commits, issues, and blog posts
• comparisons back to Happy when the finding affects product or protocol design

What does not belong here

• git checkouts of competitor repos
• git submodules
• copied source trees or vendored code dumps
• large raw logs, binaries, or secrets

If you need a checkout for research, keep it outside this repository. Prefer the existing adjacent area under ../happy-adjacent/research/{vendor} when it exists; otherwise use another machine-local path that is not committed.

Recommended layout

docs/competition/
├── AGENTS.md
├── comparison-matrix.md            # cross-vendor summary by topic
├── claude/
│   ├── README.md                   # high-level overview and key takeaways
│   ├── sources.md                  # upstream URLs, commit hashes, dates reviewed
│   ├── message-protocol.md         # envelopes, streaming events, turn boundaries
│   ├── session-lifecycle.md        # startup, resume, interruption, teardown
│   └── artifacts/                  # screenshots, tiny trace snippets, diagrams
├── codex/
│   └── ...
└── opencode/
    └── ...

Per-vendor file expectations

Each vendor folder should start small and stay focused:

• README.md: what this product is, what was inspected, and the main findings
• sources.md: repo URL, docs links, commit/tag reviewed, and review date
• topic files such as message-protocol.md, tool-calling.md, subagents.md, task-tracking.md, modes-and-permissions.md, or sandbox.md when those topics matter
• artifacts/: only small evidence files that help explain the writeup

Do not mirror the competitor's repo layout here. Write the conclusions we want to keep.

Research workflow

1. Inspect the competitor from a local checkout, docs site, product behavior, or captured traces.
2. Record the exact upstream references in sources.md.
3. Write the distilled result in the vendor folder.
4. Extract reusable comparisons into comparison-matrix.md when multiple vendors cover the same topic.

Current priorities

Start with the protocol and control surfaces that matter most for Happy:

• message protocol and event envelopes
• tool call representation and streaming
• subagents / task delegation model
• task tracking / todo surfaces
• mode switching and model switching
• permission / approval flow
• sandbox / workspace isolation
• session resume, fork, and interrupt behavior
• remote sync / server architecture

Current product note: OpenCode is a particularly strong reference right now. Its desktop UI, feature set, and especially the clickable context/debug surface look worth studying closely. Treat its messaging protocol as a leading design input, and dig further into how it syncs state with its server.

The rule of thumb is simple: checkouts stay outside the repo; insights and small supporting artifacts go here.