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

Agents are currently compiled into the fullsend binary (scaffold embed +
hardcoded externalAgents map). This ADR proposes making agents a
config-level concept in both org and per-repo config, so first-party and
third-party agents use the same mechanism and users can add agents to
their repo without code changes.

The implementation plan breaks the work into five phases: config schema,
CLI commands, wrapper generation from config, cleanup, and transition
to authoritative config.

Signed-off-by: Greg Allen <gallen@redhat.com>
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,189 @@
+---
+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. Both
+`HarnessNames()` and `HarnessWrappersLayer` read from these compiled-in
+sources to enumerate and generate harness wrappers.
+
+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
+install/wrapper-generation time, 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.
+
+**Wrapper generation.** `HarnessWrappersLayer` (org mode) builds the
+merged agent set and generates wrappers from it. Per-repo install
+does the same. For URL entries, both generate the same thin wrapper
+format (`base:` + `role:` + `slug:`). For local path entries, the
+harness file is used directly — no wrapper is needed since the
+content is already on disk.
+
+**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)