docs: add ADR and implementation plan for agent registration

Add ADR and implementation plan for declaring agents in config.yaml
instead of compiling them into the binary. fullsend run resolves
agents from config at runtime, loading harnesses directly from URLs
or local paths — no intermediate wrapper files on disk.

Signed-off-by: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Greg Allen <gallen@redhat.com>

Author: ggallen

docs/ADRs/NNNN-agent-registration.md

@@ -0,0 +1,87 @@
+---
+title: "NNNN. Agent registration"
+status: Accepted
+relates_to:
+  - agent-architecture
+  - agent-infrastructure
+topics:
+  - agents
+  - per-repo
+  - configuration
+  - extensibility
+---
+
+# NNNN. Agent registration
+
+Date: 2026-06-29
+
+## Status
+
+Accepted
+
+## Context
+
+Which agents fullsend knows about is currently compiled into the binary.
+Scaffold-embedded harnesses define the canonical agent set, and a
+hardcoded `externalAgents` map in `baseurl.go` extends it for agents
+extracted to standalone repos. Adding an agent requires a code change,
+extracted agents need special handling, and first-party and third-party
+agents follow different paths.
+
+The triage agent extraction to `fullsend-ai/agents`
+([ADR 0045](0045-forge-portable-harness-schema.md) Phase 4) is the
+first agent to move out of the scaffold. The registration mechanism
+must support both first-party extractions and user-defined agents
+without code changes.
+
+## Decision
+
+Make agent registration a **config-level concept**. Add an `agents`
+list to both `OrgConfig` and `PerRepoConfig`. (Note: ADR 0045 Phase 4
+previously removed the `agents` block from `OrgConfig`; this re-adds
+a field with the same YAML key but different semantics — harness
+source URLs rather than role/name/slug identity tuples.) Each entry
+is a URL or local path, with an optional name override:
+
+```yaml
+agents:
+  - https://raw.githubusercontent.com/fullsend-ai/agents/<sha>/harness/triage.yaml#sha256=<hash>
+  - name: lint
+    source: harness/my-linter.yaml
+```
+
+`fullsend run <name>` resolves agents from config at runtime, loading
+harnesses directly from URLs or local paths. No intermediate wrapper
+files are generated on disk — role and slug come from the harness
+content itself. Config entries merge additively with
+scaffold-discovered agents (config wins on name collision), enabling
+gradual migration. Once all first-party agents are extracted, config
+becomes authoritative and the scaffold fallback is removed.
+
+A `fullsend agent` CLI subcommand (`add`, `list`, `update`, `remove`)
+manages entries (single-user CLI operations; no concurrency guard on
+config read/write) and auto-pins URLs to a commit SHA with an
+integrity hash. Per-repo config gains `allowed_remote_resources` so per-repo
+installs can validate base composition without an org config repo.
+Per-repo config is read from the **base branch**, not the PR branch,
+so a PR cannot inject an attacker-controlled `allowed_remote_resources`
+entry or agent source.
+
+See the [implementation plan](../plans/agent-registration.md) for
+phasing, schema details, CLI behavior, and migration mechanics.
+
+## Consequences
+
+- Anyone can add an agent to a fullsend installation via `fullsend agent add` — no code change required.
+- First-party and third-party agents follow the same registration path.
+- The additive merge model allows agents to be extracted from the scaffold one at a time without disrupting existing installations.
+- Per-repo installs no longer need org config for remote resource validation.
+- No forced migration — empty config falls back to scaffold discovery until populated.
+
+## References
+
+- [ADR 0033](0033-per-repo-installation-mode.md) -- per-repo installation mode
+- [ADR 0038](0038-universal-harness-access.md) -- URL-based resource references and integrity hashes
+- [ADR 0045](0045-forge-portable-harness-schema.md) -- harness composition via `base:` URLs
+- [ADR 0057](0057-repos-management.md) -- repos management for per-repo installations
+- [Implementation plan](../plans/agent-registration.md)

docs/architecture.md

@@ -227,6 +227,8 @@ The registry is the bridge between the abstract roles defined in [agent-architec
 
 Fullsend provides a base set of agent definitions. The adopting organization's **`.fullsend`** repository extends this with org-specific agents in its `agents/` directory, following the inheritance model: fullsend defaults, then org config, then per-repo overrides. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).)
 
+**Decided:** Agents are declared in `config.yaml` (both org and per-repo) and resolved at runtime by `fullsend run` directly from URLs or local paths — no compiled-in registry or wrapper files. See [ADR NNNN](ADRs/NNNN-agent-registration.md).
+
 **Open questions:**
 
 - How are new agent roles added, tested, and promoted to production? (See [testing-agents.md](problems/testing-agents.md).) (Functional tests provide a framework for testing agent roles against controlled fixtures — [ADR 0052](ADRs/0052-functional-tests-for-agent-pipelines.md). Promotion workflow remains open.)