Add architecture tests enforcing agent package boundaries

[khaong]

Summary

• Adds CI-enforced architecture tests that prevent agent implementations from coupling to framework internals (strategy, checkpoint, session, commands, top-level cli package)
• Relaxes the researcher skill's "Do NOT read source files" instruction — now that the boundary is enforced by tests, the researcher can reference agent.go and event.go for exact interface signatures

What the tests do

• TestAgentPackages_NoForbiddenImports: Scans all agent package imports and fails if they reference forbidden internal packages. New agent packages are auto-discovered.
• TestAgentPackages_SelfRegister: Verifies every agent package has an init() calling Register() for proper discovery.

Why

From reviewing #555 — the researcher skill had a hard "Do NOT read internal source files" instruction to prevent agents from building on internals. But agent instructions are a weak enforcement mechanism. These tests enforce the real boundary at the code level, so the doc instruction can be relaxed to useful guidance instead.

Test plan

• mise run fmt && mise run lint — clean
• Architecture tests pass for all 4 agents (claudecode, geminicli, opencode, cursor)
• Tests auto-discover new agent packages — no maintenance needed when adding agents

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Adds new CI-enforced architecture tests that will fail builds if agent implementations import disallowed internal packages or forget to self-register, which could introduce unexpected breakage when adding/updating agents.

Overview
Adds architecture tests in cmd/entire/cli/agent/architecture_test.go that auto-discover agent implementation subpackages and enforce dependency boundaries, failing if they import framework internals (e.g. strategy, checkpoint, session, commands) or the top-level cli package, and requiring all agent packages to have an init() that calls Register().

Updates the researcher skill guidance to allow referencing cmd/entire/cli/agent/agent.go and event.go for authoritative interface/EventType names while still discouraging deeper internal coupling (now enforced by the new tests).

^{Written by Cursor Bugbot for commit 0051efb. Configure here.}

[Copilot]

Pull request overview

This PR adds “architecture tests” to enforce package-boundary rules for agent implementations in the Entire CLI, and updates the agent-integration researcher skill docs to allow referencing the public agent contract source files (agent.go, event.go) now that boundaries are CI-enforced.

Changes:

• Added architecture_test.go under cmd/entire/cli/agent/ to (1) forbid agent implementations from importing internal framework packages and (2) require each agent package to self-register via init().
• Updated the researcher skill documentation to permit referencing agent.go/event.go as ground truth while continuing to discourage reading deeper internals.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
cmd/entire/cli/agent/architecture_test.go	Adds CI-enforced architecture tests for agent package import boundaries and self-registration.
.claude/skills/agent-integration/researcher.md	Relaxes researcher guidance to allow consulting the agent contract source for exact interfaces/constants.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Missing continue after forbidden import causes misleading error
  • Added an isForbidden flag in the forbidden suffix loop and a continue after it to skip the allowed-prefix check for explicitly forbidden imports.
• ✅ Fixed: SelfRegister test silently passes with zero packages
  • Added len(agentPkgs) == 0 guard with t.Fatal to TestAgentPackages_SelfRegister, matching the existing guard in TestAgentPackages_NoForbiddenImports.

Or push these changes by commenting:

@cursor push 4c98db8422

Preview (4c98db8422)

diff --git a/cmd/entire/cli/agent/architecture_test.go b/cmd/entire/cli/agent/architecture_test.go
--- a/cmd/entire/cli/agent/architecture_test.go
+++ b/cmd/entire/cli/agent/architecture_test.go
@@ -80,11 +80,16 @@
 
 				// Check forbidden suffixes
 				rel := strings.TrimPrefix(imp, repoPrefix)
+				isForbidden := false
 				for _, forbidden := range forbiddenSuffixes {
 					if rel == forbidden || strings.HasPrefix(rel, forbidden+"/") {
 						t.Errorf("forbidden import %q — agent packages must not import %s internals", imp, forbidden)
+						isForbidden = true
 					}
 				}
+				if isForbidden {
+					continue
+				}
 
 				// Check it's in the allowed list
 				allowed := false
@@ -186,6 +191,10 @@
 	agentDir := findAgentDir(t)
 	agentPkgs := discoverAgentPackages(t, agentDir)
 
+	if len(agentPkgs) == 0 {
+		t.Fatal("no agent packages found — test setup is broken")
+	}
+
 	for _, pkgDir := range agentPkgs {
 		pkgName := filepath.Base(pkgDir)
 		t.Run(pkgName, func(t *testing.T) {

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[khaong]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.