docs: clarify mint role vs identity so custom agents work by default by waynesun09 · Pull Request #6772 · fullsend-ai/fullsend

waynesun09 · 2026-08-29T22:37:17Z

Problem

Users following the Customizing agents guides hit an opaque 403 from the token mint. The docs conflated two harness fields and implied any name works:

custom-agent-identity.md opened with "agents authenticate ... via the slug field" and "set slug in your harness and go."
bring-your-own-agent.md's canonical example used role: my-agent (a name the mint doesn't serve → 403), with slug commented as "GitHub App identity."

Ground truth (verified against the mint code): the mint issues identity and permissions from role; slug is an install-time hint the mint never reads; and the hosted mint serves only a fixed built-in role set. A made-up role: returns 403.

What this changes

Makes the default-mint path succeed and draws a clear line between the hosted mint and your own mint:

custom-agent-identity.md — rewritten UX-first: corrects the role/slug model, adds a default-vs-own-mint decision table, and shows that most customization — and even a brand-new agent — needs no custom identity, just a built-in role:. Custom identity / permissions / roles require your own (standalone) mint.
bring-your-own-agent.md — canonical example now uses a served role (role: triage) with a "role is not the agent's name" callout; adds a 403 row to Troubleshooting.
customizing-overview.md / customizing-agents.md — note the hosted mint's fixed role set and that the code/fix agents both run as the coder role.
harness-reference.md — role must be a role the mint serves (403 otherwise); slug is install-time only and not read by the mint; field examples updated.
building-custom-agents.md (deprecated) — example no longer 403s.

Docs-only. Relates to #6563 (BYOA role selection).

🤖 Generated with Claude Code

Users following the "customizing agents" guides hit an opaque 403 from the token mint because the docs conflated `role` and `slug` and implied any name works. Ground truth: the mint issues identity AND permissions from `role`; `slug` is an install-time hint the mint never reads; and the hosted mint serves only a fixed built-in role set. A made-up `role:` (e.g. the guides' own `role: my-agent`) returns 403. This pass makes the default-mint path succeed and draws a clear line between what works on the hosted mint vs what needs your own mint: - custom-agent-identity.md: rewritten UX-first — corrects the role/slug model, adds a default-vs-own-mint decision table, and shows that most customization (and even a brand-new agent) needs no custom identity, just a built-in `role:`. - bring-your-own-agent.md: canonical example now uses a served role (`role: triage`) with a "role is not the agent's name" callout; adds a 403 row to Troubleshooting. - customizing-overview.md / customizing-agents.md: note the hosted mint's fixed role set and that code/fix agents both run as `coder`. - harness-reference.md: `role` must be a served role (403 otherwise); `slug` is install-time only and not read by the mint; examples updated. - building-custom-agents.md (deprecated): example no longer 403s. Relates to #6563 (BYOA role selection). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014X4fMw1vDSNwXYVh4DN1FX Signed-off-by: Wayne Sun <gsun@redhat.com>

qodo-code-review · 2026-08-29T22:37:29Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

qodo-code-review · 2026-08-29T22:37:51Z

PR Summary by Qodo

Clarify mint roles and custom agent identity setup

🐞 Bug fix 📝 Documentation 🕐 10-20 Minutes

AI Description

• Clarifies that mint roles determine GitHub App identity and permissions; slugs only aid setup.
• Updates custom-agent examples to use hosted mint roles and avoid opaque 403 responses.
• Documents when standalone mints are required for custom roles, permissions, or branding.

Diagram

graph TD
  H["Agent harness"] --> R{"Role served?"}
  R -- "Built-in" --> HM["Hosted mint"] --> SA["Shared GitHub App"]
  R -- "Custom" --> SM["Standalone mint"] --> CA["Custom GitHub App"]
  H -. "install hint" .-> S["Slug setup"]

High-Level Assessment

The documentation-first correction is the appropriate approach because it aligns every entry point with existing mint behavior without changing runtime semantics. Updating the central identity guide together with examples, references, and troubleshooting avoids leaving contradictory guidance elsewhere.

Files changed (6) +104 / -23

Documentation (6) +104 / -23

bring-your-own-agent.mdUse a hosted role in the canonical custom-agent example +13/-2

Use a hosted role in the canonical custom-agent example

• Replaces the unsupported 'my-agent' role with 'triage' and explains that roles select mint identity and permissions rather than naming agents. Adds targeted troubleshooting for unsupported-role 403 responses and directs custom roles to standalone mint setup.

docs/guides/user/bring-your-own-agent.md

building-custom-agents.mdPrevent deprecated guide example from requesting an unsupported role +1/-1

Prevent deprecated guide example from requesting an unsupported role
• Changes the sample harness to use the hosted 'triage' role and clarifies that the role is not the agent name.
docs/guides/user/building-custom-agents.md

custom-agent-identity.mdReframe custom identity guidance around mint ownership +77/-12

Reframe custom identity guidance around mint ownership

• Rewrites the guide to distinguish 'role'-driven identity and permissions from the install-only 'slug'. Adds hosted-versus-standalone guidance, explains when built-in roles are sufficient, and documents custom mint setup and fallback adoption.

docs/guides/user/custom-agent-identity.md

customizing-agents.mdDocument the hosted mint's fixed role model +5/-1

Document the hosted mint's fixed role model

• Explains that agent names and mint roles are separate, role permissions are fixed, and both 'code' and 'fix' use the 'coder' identity. Links readers to custom identity guidance for role selection and standalone mint requirements.

docs/guides/user/customizing-agents.md

customizing-overview.mdClarify identity requirements for bring-your-own agents +4/-3

Clarify identity requirements for bring-your-own agents
• States that newly built agents can use the hosted mint by selecting a built-in role. Clarifies that a distinct GitHub App identity requires a standalone mint.
docs/guides/user/customizing-overview.md

harness-reference.mdCorrect role and slug field semantics +4/-4

Correct role and slug field semantics

• Updates harness examples and field definitions to show that 'role' controls mint credentials and permissions while 'slug' is only an install-time hint. Documents the hosted role set, unsupported-role 403 behavior, and the standalone mint requirement for custom roles.

docs/reference/harness-reference.md

github-actions · 2026-08-29T22:38:54Z

Site preview

Preview: https://8f7d2d4c-site.fullsend-ai.workers.dev

Commit: 89827d7eece61c22655d51f93af10f8b939dbffa

fullsend-ai-review · 2026-08-29T22:39:09Z

🤖 Finished Review · ✅ Success · Started 10:39 PM UTC · Completed 10:56 PM UTC

Commit: 89827d7 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $7.13

codecov · 2026-08-29T22:40:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

fullsend-ai-review · 2026-08-29T22:56:23Z

Risk Assessment: moderate (2/5)

Details

Docs-only PR with no protected paths, no security-sensitive files, and no dependency changes, but Tier 2 churn analysis shows several changed files are documentation hotspots with high recent commit frequency (avg 13.67 commits/30d) and many distinct authors (avg 5.33/90d), justifying elevation from 1 to 2.

fullsend-ai-review · 2026-08-29T22:56:25Z

Review

Findings

Medium

[technical accuracy in documentation] docs/guides/user/custom-agent-identity.md — The built-in role list in the comparison table lists only triage, coder, review, retro, prioritize, fullsend — omitting fix, which is a distinct canonical built-in role in canonicalRolePermissions (internal/mintcore/github.go) with its own permission set. The same PR modifies customizing-agents.md which already lists fix in its roles table (line 274) and explicitly mentions fix in the new introductory paragraph, creating an internal inconsistency within the PR's own output.
Remediation: Add fix to the enumerated built-in role lists, or note that fix is also a valid built-in role.
[technical accuracy in documentation] docs/guides/user/bring-your-own-agent.md:101 — The callout states role: must be one of the built-in roles triage, coder, review, retro, prioritize, fullsend — omitting fix. A user with a fix-like agent who sets role: fix would believe this is invalid based on the docs, when fix is a canonical built-in role that the hosted mint accepts.
Remediation: Add fix to the enumerated list.
[technical accuracy in documentation] docs/reference/harness-reference.md:129 — The role field description lists the hosted mint's built-in set without fix. Since fix is a canonical built-in role and the existing fix agent harness uses role: fix, this reference doc would incorrectly tell users that role: fix requires a custom mint.
Remediation: Add fix to the built-in role list.
[stale-description] docs/agents/topics/default-vs-custom.md:80 — The classification table states "The slug determines who the agent authenticates as. A different identity is a different agent." This PR establishes that slug is an install-time hint only and the mint never reads it; identity and authentication are determined by role, not slug. The table entry, its header, and footnote all describe slug as the identity/authentication mechanism, contradicting the corrected model.
Remediation: Update line 80 to reflect that identity comes from role, not slug. The slug row should be reclassified or removed.
[stale-description] docs/contributing/bot-identities.md:3 — The introductory sentence states "The GitHub App login is derived from the slug field in each harness file." This PR clarifies that slug is an install-time hint that the mint never reads — the GitHub App login is determined by role, not slug.
Remediation: Change "derived from the slug field" to "determined by the role field in each harness file."

Low

[technical accuracy in documentation] docs/guides/user/customizing-agents.md:268 — The new text states "the code and fix agents both run as the coder role." While fix shares the coder GitHub App and PEM, fix is a distinct entry in canonicalRolePermissions with a different permission ceiling (fix lacks checks:read). The built-in fix harness uses role: fix, not role: coder.
Remediation: Consider rewording to "the code and fix agents both authenticate as the coder GitHub App" to avoid implying they share the same role entry.
[internal consistency] docs/guides/user/bring-your-own-agent.md:363 — The troubleshooting table row for 403 / "role not allowed" lists the same incomplete built-in role set without fix.
Remediation: Add fix to the parenthetical list of valid built-in roles.
[inline comment capitalization] docs/reference/harness-reference.md:11 — The inline YAML comment for slug starts with a lowercase letter (# install-time App discovery ...). Every other inline comment in this reference YAML block starts with an uppercase letter (e.g., # Path to agent definition, # Human-readable description).
Remediation: Capitalize the first word: # Install-time App discovery ...
[trailing whitespace / blank lines] docs/guides/user/bring-your-own-agent.md:108 — Double blank line after the role blockquote callout. Codebase convention is a single blank line between elements.
Remediation: Remove one of the two blank lines.

Next steps:

/fs-fix — agent addresses review findings automatically
/fs-fix <your instruction> — agent fixes with your specific guidance
Push commits directly — review re-runs automatically on push
/fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review

See the review comment for full details.

fullsend-ai-review · 2026-08-29T22:56:26Z


+> **`role` is not the agent's name.** The agent's name is `name:` in its `.md`;
+> `role:` selects which GitHub App and permissions the mint issues. On the
+> default (hosted) mint, `role:` must be one of the built-in roles it serves —


[medium] technical accuracy in documentation

The callout states role: must be one of the built-in roles triage, coder, review, retro, prioritize, fullsend — omitting fix. A user with a fix-like agent who sets role: fix would believe this is invalid based on the docs, when fix is a canonical built-in role that the hosted mint accepts.

Suggested fix: Add fix to the enumerated list.

fullsend-ai-review · 2026-08-29T22:56:26Z

 Most fields are self-explanatory from the inline comments above. This section expands on fields where additional context helps.

-**`role`** — The agent's identity within fullsend. Dispatch uses the role to match config-registered agents to built-in defaults (same-name config agents take precedence). The role also determines which GitHub App credentials the mint service issues.
+**`role`** — The agent's identity within fullsend. Dispatch uses the role to match config-registered agents to built-in defaults (same-name config agents take precedence). The role also determines which GitHub App credentials **and permissions** the mint service issues. It must be a role the mint serves: on the hosted mint that is the fixed built-in set (`triage`, `coder`, `review`, `retro`, `prioritize`, `fullsend`); custom roles require your own mint. An unserved role returns `403`. See [Custom Agent Identity](../guides/user/custom-agent-identity.md).


[medium] technical accuracy in documentation

The role field description lists the hosted mint's built-in set without fix. Since fix is a canonical built-in role and the existing fix agent harness uses role: fix, this reference doc would incorrectly tell users that role: fix requires a custom mint.

Suggested fix: Add fix to the built-in role list.

fullsend-ai-review · 2026-08-29T22:56:26Z

-Each agent role has its own identity, permissions, and purpose:
+On the hosted mint, agents run as one of a **fixed** set of built-in roles.
+Each role is a GitHub App identity with a fixed permission ceiling. An agent's
+name is separate from its role — the `code` and `fix` agents both run as the


[low] technical accuracy in documentation

The new text states 'the code and fix agents both run as the coder role.' While fix shares the coder GitHub App and PEM, fix is a distinct entry in canonicalRolePermissions with a different permission ceiling (fix lacks checks:read). The built-in fix harness uses role: fix, not role: coder.

Suggested fix: Consider rewording to 'the code and fix agents both authenticate as the coder GitHub App' to avoid implying they share the same role entry.

fullsend-ai-review · 2026-08-29T22:56:26Z

 | "role field is required" | Add `role:` to harness |
+| `403` / "role not allowed" from the mint | Your `role:` is not one the mint serves. On the hosted mint use a built-in role (`triage`, `coder`, `review`, `retro`, `prioritize`, `fullsend`); for a custom role, point `FULLSEND_MINT_URL` at your own mint — see [Custom Agent Identity](custom-agent-identity.md) |
 | Agent can't find input files | Pre-script output paths must match `host_files` entries |
 | Provider blocks requests | Check that the required provider profile is listed in `providers:` and exists in the `providers/` directory |


[low] internal consistency

The troubleshooting table 403 row lists the same incomplete built-in role set without fix.

Suggested fix: Add fix to the parenthetical list of valid built-in roles.

fullsend-ai-review · 2026-08-29T22:56:26Z


 # ── Identity & metadata ──────────────────────────────────────
-slug: my-org-my-role                # GitHub App identity (convention: <org>-<role>)
+slug: my-org-my-role                # install-time App discovery (convention: <org>-<role>); not read by the mint


[low] inline comment capitalization

The inline YAML comment for slug starts with a lowercase letter (install-time App discovery). Every other inline comment in this reference YAML block starts with an uppercase letter.

Suggested fix: Capitalize the first word: Install-time App discovery ...

fullsend-ai-review · 2026-08-29T22:56:26Z

+> mint. To use a *new* role or your *own* identity, you need your own mint —
+> see [Custom Agent Identity](custom-agent-identity.md).
+
+


[low] trailing whitespace / blank lines

Double blank line after the role blockquote callout. Codebase convention is a single blank line between elements.

Suggested fix: Remove one of the two blank lines.

waynesun09 requested a review from a team as a code owner August 29, 2026 22:37

waynesun09 temporarily deployed to dev August 29, 2026 22:37 — with GitHub Actions Inactive

github-actions Bot deployed to site-preview August 29, 2026 22:38 View deployment

waynesun09 assigned rh-hemartin Aug 29, 2026

fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Aug 29, 2026

fullsend-ai-review Bot suggested changes Aug 29, 2026

View reviewed changes

rh-hemartin approved these changes Aug 31, 2026

View reviewed changes

		> mint. To use a new role or your own identity, you need your own mint —
		> see [Custom Agent Identity](custom-agent-identity.md).

Uh oh!

Conversation

waynesun09 commented Aug 29, 2026

Problem

What this changes

Uh oh!

qodo-code-review Bot commented Aug 29, 2026

Code Review by Qodo

Great, no issues found!

Uh oh!

qodo-code-review Bot commented Aug 29, 2026

PR Summary by Qodo

Uh oh!

github-actions Bot commented Aug 29, 2026

Site preview

Uh oh!

fullsend-ai-review Bot commented Aug 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Aug 29, 2026

Codecov Report

Uh oh!

fullsend-ai-review Bot commented Aug 29, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 29, 2026

Review

Findings

Medium

Low

Uh oh!

fullsend-ai-review Bot left a comment

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fullsend-ai-review Bot commented Aug 29, 2026 •

edited

Loading