docs: add ADR and implementation plan for config-driven agents

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-config-driven-agents.md

@@ -0,0 +1,187 @@
+---
+title: "NNNN. Config-driven agents"
+status: Accepted
+relates_to:
+  - agent-architecture
+  - agent-infrastructure
+topics:
+  - agents
+  - per-repo
+  - configuration
+  - extensibility
+---
+
+# NNNN. Config-driven agents
+
+Date: 2026-06-29
+
+## Status
+
+Accepted
+
+## Context
+
+Which agents fullsend knows about is currently compiled into the binary.
+Scaffold-embedded harnesses (`internal/scaffold/fullsend-repo/harness/`)
+define the canonical agent set, and a hardcoded `externalAgents` map in
+`baseurl.go` extends it for agents extracted to standalone repos. `HarnessNames()` reads from these compiled-in sources to determine
+which agents are available.
+
+This creates three problems:
+
+1. **Adding an agent requires a code change.** A user who wants to run a
+   custom agent must modify the fullsend binary or work around it.
+2. **First-party agents extracted to external repos need special
+   handling.** The `externalAgents` map is a one-off mechanism that pins
+   commit SHAs and content hashes in Go source.
+3. **First-party and third-party agents follow different paths.**
+   Fullsend's own agents are discovered from the scaffold embed;
+   external agents are discovered from a hardcoded map. There is no
+   single, uniform mechanism.
+
+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. More will follow. The
+registration mechanism must support both first-party extractions and
+user-defined agents without code changes to fullsend.
+
+## Decision
+
+Make agent registration a **config-level concept** in both org config
+and per-repo config.
+
+**Config schema.** Add an `agents` list to both `OrgConfig` and
+`PerRepoConfig`. Each entry is either a string shorthand or an object
+with an explicit name. The source can be a URL (for remote harnesses)
+or a local path (for harnesses on disk):
+
+```yaml
+# Per-repo config (.fullsend/config.yaml in target repo)
+version: "1"
+agents:
+  # String shorthand — name derived from filename
+  - https://raw.githubusercontent.com/fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/code.yaml#sha256=<hash>
+  - harness/my-custom-agent.yaml
+
+  # Object form — explicit name overrides filename
+  - name: triage
+    source: https://raw.githubusercontent.com/fullsend-ai/agents/<sha>/harness/triage.yaml#sha256=<hash>
+  - name: lint
+    source: harness/my-linter.yaml
+allowed_remote_resources:
+  - https://raw.githubusercontent.com/fullsend-ai/fullsend/
+  - https://raw.githubusercontent.com/fullsend-ai/agents/
+```
+
+An entry's source is treated as a URL if it starts with `https://`,
+and as a local path otherwise. Local paths resolve relative to the
+`.fullsend/` directory. When `name` is omitted (string shorthand), the
+agent name is derived from the filename (`triage.yaml` -> `triage`).
+When `name` is provided, it overrides the filename-derived name. Role and slug are read from the harness content at runtime, not
+stored in config. URL entries
+include an integrity hash fragment for content verification
+([ADR 0038](0038-universal-harness-access.md)); local paths do not
+require one since the content is already trusted on disk.
+
+**`allowed_remote_resources` in per-repo config.** This field currently
+exists only in org config. Per-repo config gains it to support base
+composition without an org config repo. Both are checked at load time;
+per-repo entries are additive.
+
+**Install seeding.** During install, the default first-party agent
+URLs are populated into `agents` — in org config for org-mode
+installs (`fullsend admin install <org>`), in per-repo config for
+per-repo installs (`fullsend github` / `fullsend admin install
+<owner/repo>`). They use the same format as any user-added agent. The
+`--agents` flag continues to control which roles are installed; the
+mapping from role to default harness URL is a build-time constant (not
+a runtime concept).
+
+**CLI surface.** A `fullsend agent` subcommand group manages the
+agents list in config:
+
+| Command | Effect |
+|---------|--------|
+| `fullsend agent add <url-or-path>` | Fetch/read harness, validate, append to config |
+| `fullsend agent list` | List registered agents with name, role, source |
+| `fullsend agent update <name> [sha]` | Re-pin agent to latest HEAD or a specific commit |
+| `fullsend agent remove <name>` | Remove agent entry from config |
+
+`agent add` accepts a URL or a local path and validates the harness
+before appending it to config. `agent update` re-pins a URL-based
+agent to a new commit (latest HEAD or a specific SHA). Both commands
+automatically resolve unpinned URLs to fully pinned form — commit SHA
+and integrity hash are resolved and computed by the CLI so users never
+need to construct pinned URLs manually. The stored config entry is
+always fully pinned.
+
+**Additive merge model.** Config entries are merged with
+scaffold-discovered agents, not a replacement. Scaffold agents form
+the base set; config entries add new agents or override scaffold
+entries with the same name. The merge rule: config wins over scaffold
+when names collide. This enables gradual migration — agents can be
+extracted one at a time without requiring every config to list all
+agents.
+
+`fullsend agent list` shows the merged view (scaffold + config) so
+the full agent set is visible in one place.
+
+**Runtime resolution.** `fullsend run <name>` looks up the agent by
+name in the merged agent set. For URL entries, it loads the harness
+directly from the URL — no intermediate wrapper file is generated on
+disk. For local path entries, the harness is loaded directly from the
+path. Role and slug come from the harness content itself, so no
+wrapper is needed to inject identity fields.
+
+**Removal of compiled-in agent map.** The `externalAgents` map,
+`IsExternalAgent()`, and the external-agent branches in
+`HarnessBaseURL()`/`HarnessContentHash()` are deleted.
+`HarnessNames()` returns only scaffold-embedded names (used as the
+base set for the additive merge).
+
+**Transition to authoritative config.** The additive model is a
+migration aid. Once all first-party agents have been extracted from
+the scaffold and all installations have populated `agents` in config,
+a follow-up change makes config authoritative: scaffold agents are no
+longer discovered, and `agents` is the complete list. An issue will
+be filed to track this transition once the last agent is extracted.
+
+## Consequences
+
+- **Extensibility.** Anyone can add an agent to the fullsend installation in their repo with
+  `fullsend agent add <url-or-path>` — no code change, no PR to
+  fullsend. Local paths support development and private harnesses.
+- **Uniform path.** First-party and third-party agents are registered
+  the same way. Extracting an agent to a standalone repo is a config
+  update, not a code change.
+- **Gradual migration.** The additive merge model means agents can be
+  extracted from the scaffold one at a time. Users only need config
+  entries for agents that have moved or been added — unchanged
+  scaffold agents continue to work. Once all agents are extracted,
+  config becomes authoritative and the scaffold fallback is removed.
+- **Org config dependency removed for per-repo installs.**
+  `allowed_remote_resources` in per-repo config eliminates the need
+  to read org config for base composition validation.
+- **Migration.** No forced migration. Existing installations continue
+  to work without changes:
+  - When `agents` is empty in config, the code falls back to the
+    current scaffold-based agent discovery. This fallback is
+    permanent until the config is populated — there is no deadline.
+  - Per-repo configs that lack `allowed_remote_resources` inherit
+    the org-level allowlist (if present) or use the scaffold
+    fallback path, which does not require an allowlist.
+  - To opt in, users can run `fullsend agent add` to populate the
+    list manually, or the config is backfilled automatically the
+    next time they run `fullsend admin install --upgrade`,
+    `fullsend github` (re-install), or `fullsend repos sync`
+    ([ADR 0057](0057-repos-management.md)).
+  - A deprecation notice is logged when the fallback is used, to
+    nudge users toward populating the config.
+
+## 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/config-driven-agents.md)