Adding new agent adapters: recipe for the next 14 (post #119 + #145)

[harshitsinghbhandari]

What just landed

• feat(agents): agent platform — registry, activity hooks, harness allowlist #119 — feat(agents): agent platform — registry, activity hooks, harness allowlist (the platform sub-stack: adapters/agent/{registry,activitydispatch,hookutil}, CLI hooks command, daemon wiring, shared ports.MetadataKey*, openapi/schema deltas, SQLite migration 0007_allow_implemented_harnesses.sql widening the sessions.harness CHECK to allow all 19 planned harness strings).
• feat(agents): add grok, cursor, qwen, copilot, kimi adapters #145 — feat(agents): add grok, cursor, qwen, copilot, kimi adapters (5 adapters wired on top of the platform, batched into one PR).

main now has these adapters registered in registry.Constructors(): claudecode, codex, opencode, grok, cursor, qwen, copilot, kimi.

The other 14 adapter directories yyovil prepared are not yet on main. Their work lives on origin/agents/02-droid through origin/agents/20-autohand, except those merged into #145.

How to add the remaining 14 (do NOT just open PRs from agents/* branches)

The agents/<n>-<name> branches are a linear stack on top of the pre-platform agents/00-platform. If you open a PR from, say, agents/10-goose to main, you will be re-proposing every commit in the stack underneath it (platform, grok, droid, amp, agy, crush, aider, cursor, qwen, copilot — most of which is either already on main or you're skipping). Don't do that.

Instead: cherry-pick the adapter's own commit onto a fresh branch off main. You can batch multiple adapters into one PR (that's what #145 did for the first five).

Recipe

git fetch origin
git checkout -b land/<name> origin/main
git cherry-pick <commit>             # see table
cd backend && go build ./... && go test -race ./...
git push -u origin land/<name>
gh pr create --base main --title "feat(agents): add <name> adapter"

That's the whole job per adapter.

Cherry-pick commits for the remaining 14

Adapter	Branch	Cherry-pick
droid	agents/02-droid	3f94a65
amp	agents/03-amp	dbb800e
agy	agents/04-agy	0da8825
crush	agents/05-crush	8ff7b3a
aider	agents/06-aider	e37fef8
goose	agents/10-goose	b936443
auggie	agents/11-auggie	6ffac86
continue	agents/12-continue	afb9430 (directory is adapters/agent/continueagent/ — continue is a Go keyword)
devin	agents/13-devin	0cb96f6
cline	agents/14-cline	3925e6b
kiro	agents/16-kiro	1e6b496
kilocode	agents/17-kilocode	1c58723
vibe	agents/18-vibe	302cab3
pi	agents/19-pi	2d73665
autohand	agents/20-autohand	8c3e9d9

Things that may confuse the next person

1. Three squash-merge tips on the stack — NOT the right commits

These commits exist on yyovil's branches but you do not want them:

Squash-merge commit	On branch	Why it's wrong
3cbd7c1	agents/07-cursor	squash of PR #127 (qwen into cursor). Already represented on main by 1fa8ed7.
fac804b	agents/08-qwen	squash of PR #128 (copilot into qwen). Includes the aa-63 hook fix inline; the equivalent is on main via #145.
44964c5	agents/14-cline	squash of PR #134 (kimi into cline). The corresponding kimi work is on main via #145.

The 14 remaining adapter commits in the table above are clean single yyovil commits and are safe to cherry-pick directly.

2. Migration 0007 already allows every harness — don't add a new migration per adapter

backend/internal/storage/sqlite/migrations/0007_allow_implemented_harnesses.sql widens the sessions.harness CHECK in one go to allow:

'', claude-code, codex, aider, opencode,
grok, droid, amp, agy, crush, cursor, qwen, copilot,
goose, auggie, continue, devin, cline, kimi, kiro, kilocode,
vibe, pi, autohand

So a new adapter PR does NOT need its own migration. It only needs to:

1. Add the adapter package under backend/internal/adapters/agent/<name>/
2. Append <name>.New(), to registry.Constructors() in backend/internal/adapters/agent/registry/registry.go
3. Append the harness to backend/internal/daemon/wiring_test.go

The harness string constant in backend/internal/domain/harness.go is already there for all 19 — the platform PR added them upfront.

Trade-off worth knowing: because the CHECK is broad, the DB will accept --harness=goose today even though goose isn't wired. Session start will fail at registry lookup. That's an accepted state until the remaining adapters land.

3. The local gate is just go build + go test -race

Do NOT run agent-ci. Do NOT touch .github/agent-ci.Dockerfile. The gate is:

cd backend && go build ./... && go test -race ./...

4. Batch or single — both fine

#145 batched 5 adapters into one PR. That worked because the adapters are mutually independent (each one only touches its own directory + 2 lines in registry.go + 1 in wiring_test.go). You can do the same for the next batch — group however many feel reviewable.

5. Quality signals on yyovil's remaining adapters

From the audit (/tmp/aa-stack-map.md is the source if anyone has it):

• Every remaining adapter has tests (<name>_test.go in its directory).
• All reference ports.MetadataKey{Title,Summary} (added by the platform commit).
• droid, agy use hookutil.AtomicWriteFile. The rest do their own file writes.
• No adapter depends on any other adapter — they only depend on the platform.

If you're reviewing them: focus on the adapter's own hooks.go (the actual integration with the agent's hook config format) and <name>_test.go. The other files (<name>.go, optional activity.go) are mostly boilerplate following the pattern from claudecode/codex/opencode.

Background

Full read-only audit of the original yyovil stack — chain shape, conflict surface, per-adapter quality, strategy comparison — is in commit history if needed. The TL;DR is that yyovil built one linear stack with a load-bearing platform commit at the bottom and 20 single-adapter commits on top. Strategy "land platform first, then cherry-pick adapters onto main" was the chosen path; that's how #119 and #145 happened, and that's the same path for the remaining 14.