Harness-driven dispatch routing: eliminate per-agent workflow files for custom agents

[ralphbean]

What happens

Adding a custom agent to a fullsend installation today requires five steps in the .fullsend repo:

1. Allowlist the agent's source domain in config.yaml allowed_remote_resources
2. Enable the role in config.yaml defaults.roles
3. Add a harness file (e.g. customized/harness/uber.yaml) referencing the remote agent definition, skills, and policy
4. Add a GitHub Actions workflow file (e.g. .github/workflows/uber.yml) with a # fullsend-stage: marker that calls a reusable workflow
5. Add dispatch routing logic to dispatch.yml (or rely on a slash command) so events reach the new stage

Steps (4) and (5) are boilerplate. The workflow file is a thin shim that passes inputs to a reusable workflow and names the harness. The dispatch routing wires events to the stage. Neither contains agent-specific logic — they exist only because the dispatch router discovers agents by scanning workflow files for # fullsend-stage: markers.

A second friction point: ValidRoles() in internal/config/config.go is a hardcoded allowlist. Custom roles fail config validation without modifying the fullsend binary.

What should happen

Steps (4) and (5) should be expressible entirely via the harness file in step (3). An org admin adding a custom agent should only need to:

1. Allowlist the source in config.yaml
2. Enable the role in config.yaml
3. Add a harness file

The harness YAML would declare its trigger conditions, e.g.:

agent: https://raw.githubusercontent.com/ralphbean/uber-agent/<commit>/agents/uber.md#sha256=abc123...
triggers:
  - event: issues
    action: labeled
    label: needs-uber
  - event: issue_comment
    command: /fs-uber
# ...

The dispatch router would read trigger declarations from harness files at dispatch time instead of scanning workflow files for stage markers. A single generic reusable workflow would handle execution for any harness.

ValidRoles() should accept any role matching ^[a-z][a-z0-9_-]*$ that has a corresponding harness file, rather than requiring the role to be in a hardcoded list.

Context

This is a prerequisite for making third-party agent installation simple enough that an org admin can drop in an external agent (e.g. from github.com/ralphbean/uber-agent) with minimal configuration. It also sets the stage for re-platforming fullsend's default agents to use the same mechanism.

Related:

• ADR 0038 — Universal harness access via URLs (provides the remote reference mechanism)
• ADR 0035 — Layered content resolution (provides the customization overlay model)
• Investigate plugin repository approach for community/custom agents #631 — Investigate plugin repository approach for community/custom agents
• docs: add automated regression test for the adding-custom-agents guide #554 — Regression test for the adding-custom-agents guide

[ralphbean]

This is important for redhat-developer. Right now if they want to add a custom agent, they have to fumble with workflow files and dispatch routing that are really just boilerplate — and the result still feels like a second-class citizen next to the built-in agents. If we can get harness-driven routing working, adding a new agent becomes a config change instead of an infrastructure change, which is where we want to be.

/fs-prioritize

[fullsend-ai-triage]

Triage Summary

Category: Feature — harness-driven dispatch routing to simplify custom agent onboarding
Severity: Medium

Problem

Adding a custom agent currently requires five steps, two of which (workflow file and dispatch routing) are pure boilerplate containing no agent-specific logic. Additionally, ValidRoles() is a hardcoded allowlist that rejects custom role names without modifying the fullsend binary.

Root Cause

The dispatch router discovers agents by scanning workflow files for # fullsend-stage: markers rather than reading declarations from harness files. Role validation uses a static list instead of dynamically checking for corresponding harness files.

Recommended Approach

1. Extend the harness YAML schema with a triggers field for event/action/label/command routing
2. Modify the dispatch router to read trigger declarations from harness files
3. Create a single generic reusable workflow for harness-driven agents
4. Make ValidRoles() dynamic — accept any role matching ^[a-z][a-z0-9_-]*$ with a corresponding harness file

Key files: internal/config/config.go (ValidRoles), dispatch router, harness YAML schema.

Proposed Test Case

- ValidRoles dynamic validation:
  - Create harness file for custom role 'uber' → config validation accepts it
  - No harness file for role 'uber' → config validation rejects it
  - Role name with invalid chars (e.g. 'Uber!') → rejected

- Dispatch routing from harness triggers:
  - Harness with trigger {event: issues, action: labeled, label: needs-uber}
    → dispatch routes matching event to correct harness
  - Harness with trigger {event: issue_comment, command: /fs-uber}
    → dispatch routes matching comment to correct harness
  - No dedicated workflow file needed

- Edge cases:
  - Harness with no triggers field → validation error
  - Duplicate trigger patterns across harnesses → warning or error

Related Issues

• Re-platform default agents as harness-driven configs, not scaffold-embedded artifacts #1986 (re-platform default agents) depends on this work
• Investigate plugin repository approach for community/custom agents #631 (plugin repository approach) explores a complementary direction
• docs: add automated regression test for the adding-custom-agents guide #554 (regression test for adding-custom-agents guide) — guide will need updating after this lands

---

Labels: Feature request touching both harness config/loading and dispatch routing components, with medium priority given it unblocks third-party agent adoption.

[ralphbean]

/fs-prioritize

[fullsend-ai-prioritize]

RICE Priority Score: 0.9

Score breakdown

Dimension	Score	Reasoning
Reach	1.5	This affects multiple organizations adding custom agents — ralphbean explicitly mentions redhat-developer as impacted. It also unblocks third-party agent adoption broadly and is a prerequisite for re-platforming default agents (#1986), which would eventually affect all users. Scoring 1.5 for multiple strategic customers.
Impact	1.5	The current 5-step process includes two steps of pure boilerplate (workflow file + dispatch routing) and a hardcoded ValidRoles that blocks custom roles entirely without modifying the binary. Eliminating this friction converts an infrastructure change into a config change — a significant improvement for affected users, but not blocking core functionality. Scoring 1.5 for significant pain point.
Confidence	0.8	The issue is exceptionally well-described with clear problem statement, proposed solution, related ADRs, and a detailed triage summary identifying key files. The scope is well-understood. Scoring 0.8 for high confidence.
Effort	2	Requires modifying the dispatch router to read triggers from harness files instead of scanning workflow markers, extending the harness YAML schema with a triggers field, making ValidRoles dynamic in internal/config/config.go, and creating a generic reusable workflow. Touches multiple components (dispatch, harness, config validation) with design work needed. Scoring 2 for complex implementation.

Formula: (1.5 x 1.5 x 0.8) / 2 = 0.9