Escalation ladder for changing agent behavior

Status: Proposed. Level names and evidence-to-escalate criteria are a working proposal pending maintainer agreement on #5372. Treat this as guidance under review, not settled project policy.

Before replacing or deriving from a core agent, prove that lighter options cannot meet your needs. This page defines the escalation path — start at Level 1 and move up only when you can show why the current level is insufficient.

This ladder applies to core agent roles that fullsend already ships (triage, code, review, fix, retro, prioritize). If you are building an agent for a job fullsend does not cover — a release-notes generator, a compliance checker, a deployment orchestrator — skip ahead to Bring Your Own Agent. There is no existing default to exhaust first.

The four levels

Level 1 — Configure           Least invasive. No code leaves your repo.
Level 2 — Contribute          Fix the gap in the default agent for everyone.
Level 3 — Derive              Inherit the default, replace identity components.
Level 4 — Replace             Build a parallel agent for the same role.

Each level increases maintenance burden. A derived agent inherits upstream improvements via base but must track breaking changes in the parent harness. A replacement agent inherits nothing — every upstream improvement must be replicated independently.

Level 1: Configure the default agent

Use the extension points the default agent was designed for. These keep you in configured-default territory and require no changes to the agent's identity-defining fields. Some rows need a thin base-composed harness (still Level 1); others need no harness at all.

Extension point	What it does	Guide
AGENTS.md	Project-wide instructions for all agents — code style, test commands, architecture rules, domain context. No harness required.	Customizing with AGENTS.md
Repo skills (.agents/skills/)	Domain-specific knowledge for individual agents — linting rules, deployment checklists, label glossaries. No harness required.	Customizing with Skills
Documented env vars	Per-agent tuning knobs (e.g., REVIEW_FINDING_SEVERITY_THRESHOLD). No harness required.	Each agent's reference page
env: in harness	Add environment variables without changing the agent's identity. Needs a thin base harness.	Harness Field Reference
skills: in harness	Add skills via base composition — concatenated with the base agent's skill list. Needs a thin base harness.	Configuring Agent Behavior
plugins: in harness	Add language-server plugins. Needs a thin base harness.	Harness Field Reference
host_files: in harness	Inject additional files into the sandbox. Needs a thin base harness.	Harness Field Reference
Sandbox image layers	Base your image on the default, add tools; point the harness image: field at it. Needs a thin base harness.	Extending the sandbox image

Evidence to escalate: show that no combination of these extension points produces the behavior you need. Concrete evidence includes:

• A failing test case or eval run where the agent consistently gets the wrong answer despite correct AGENTS.md instructions
• A skill that cannot influence the agent's behavior because the gap is in the system prompt, not in domain knowledge
• An env var or config knob that does not exist for the behavior you need to change

Level 2: Contribute to the default agent

If Level 1 cannot close the gap, check whether the gap is general — would other users benefit from the same change? If yes, the fix belongs in the default agent, not in a private fork.

Contributions include:

• New extension points — a new env var, a new skill hook, a new documented configuration knob
• Prompt improvements — clarifications, better instructions, additional decision criteria in the agent definition
• Script changes — pre/post script logic that handles a broader set of cases
• Skill improvements — better procedures, additional steps, broader coverage in a built-in skill

How to contribute: file an issue or open a PR against the default agent. If the change is in the fullsend-ai/fullsend repo (harness, scripts, skills, agent definitions), contribute there. If the agent definition or harness lives in fullsend-ai/agents, contribute to that repo instead. First-time contributors must be vouched by a maintainer before opening a PR — unvouched PRs are auto-closed.

Evidence to escalate: show that the improvement you need is specific to your team's workflow and would not benefit other users. Concrete evidence includes:

• A proposed upstream change that was reviewed and rejected as too org-specific
• A behavior change that contradicts the default agent's documented charter (e.g., you need the review agent to auto-merge, but the default review agent is explicitly read-only)
• A workflow that requires proprietary integrations (e.g., posting to an internal Slack channel, querying a private API)

Level 3: Derive from the default agent

Inherit the default harness via base and replace only the components that must differ. This is a derived agent — it tracks upstream improvements for everything you did not override, but the components you replaced are now your responsibility.

Derived agents use base composition to inherit the default harness and override identity-defining fields:

base: https://raw.githubusercontent.com/fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/code.yaml#sha256=abc...

# Override identity-defining components:
agent: agents/my-code-agent.md          # Custom system prompt
post_script: scripts/post-my-code.sh    # Custom post-processing
slug: my-org-code                       # Custom identity

See Configuring Agent Behavior for the full pattern and Classification by harness field for which fields cross the derived threshold.

What you maintain:

• Your custom system prompt, scripts, or validation loop
• Compatibility with upstream base harness changes (field additions, schema changes, script interface changes)
• Your own testing and evaluation for the overridden components

Evidence to escalate: show that base inheritance cannot support your use case. Concrete evidence includes:

• A fundamental incompatibility with the base harness's script interface (e.g., the base post-script expects an output format your agent does not produce, and you cannot adapt either side)
• A need to remove or replace a provider the base harness already declares — providers: entries are concatenated (base + child), not subtractive. Sandbox policy and image can already be fully overridden at Level 3 via a scalar field replacement

Level 4: Replace the role entirely

Build a custom agent from scratch that fills the same role as a default agent. This is the heaviest option — you inherit nothing from upstream and must maintain the full harness, agent definition, scripts, skills, and testing independently.

See Bring Your Own Agent for the end-to-end guide.

When this is appropriate:

• The default agent's architecture is fundamentally incompatible with your requirements (not just its prompt or scripts)
• You have passed through Levels 1–3 and documented why each is insufficient
• You have the capacity to maintain a parallel implementation long-term

Register your replacement agent with the same role name in config.yaml — config-registered agents take precedence over built-in agents on name collision. See Registering your agent.

Prove-it checklist

Before creating a derived or replacement agent for a core role, confirm:

• [ ] Level 1 exhausted. You tried AGENTS.md, repo skills, env vars, harness skills: / plugins: / host_files:, and documented config knobs. None of them address the gap.
• [ ] Level 2 considered. The improvement is too org-specific to contribute upstream, or an upstream contribution was proposed and rejected.
• [ ] Level 3 evaluated (if jumping to Level 4). base inheritance cannot support your use case, and you can articulate why.
• [ ] Evidence documented. You have specific examples — failed eval runs, rejected upstream PRs, architectural constraints — not just a preference for a different approach.
• [ ] Maintenance plan. You have a plan for keeping the derived or custom agent up to date as the default evolves.

See also

• Default, derived, and custom agents — how to classify your agent after making changes
• Bring Your Own Agent — building and registering custom agents
• Customizing with AGENTS.md — Level 1: project-wide instructions
• Customizing with Skills — Level 1: agent-specific domain knowledge
• Configuring agent behavior — harness configurations and base: composition