From ecf4e257a2d3c033505653e9f029b69c39e1ce99 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Tue, 7 Jul 2026 14:27:45 -0400 Subject: [PATCH 1/7] docs(agents): clarify default vs. custom agent distinction Add docs/agents/topics/default-vs-custom.md defining when customization of a default agent crosses into custom agent territory. The rule: if a modification uses a documented extension point for that agent, it's still a configured default agent. Otherwise it's a custom agent re-using parts of a default. Link to the new doc from docs/agents/README.md, docs/guides/README.md, and the three customization guides in docs/guides/user/. Assisted-by: Claude claude-opus-4-6 Signed-off-by: Ralph Bean --- docs/agents/README.md | 4 + docs/agents/topics/default-vs-custom.md | 92 +++++++++++++++++++ docs/guides/README.md | 1 + docs/guides/user/building-custom-agents.md | 3 + docs/guides/user/customizing-agents.md | 1 + .../guides/user/customizing-with-agents-md.md | 5 + docs/guides/user/customizing-with-skills.md | 5 + 7 files changed, 111 insertions(+) create mode 100644 docs/agents/topics/default-vs-custom.md diff --git a/docs/agents/README.md b/docs/agents/README.md index 5c47287c1..500e4ceda 100644 --- a/docs/agents/README.md +++ b/docs/agents/README.md @@ -23,6 +23,10 @@ a specific agent performs a specific task. See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and [Customizing with Skills](../guides/user/customizing-with-skills.md). +At some point, enough customization turns a configured default agent into a +custom agent. See [Default agents vs. custom agents](topics/default-vs-custom.md) +for where that line is and why it matters. + ## Custom Agents Custom agents can be added to the fullsend pipeline via the `agents:` field in diff --git a/docs/agents/topics/default-vs-custom.md b/docs/agents/topics/default-vs-custom.md new file mode 100644 index 000000000..d690be025 --- /dev/null +++ b/docs/agents/topics/default-vs-custom.md @@ -0,0 +1,92 @@ +# Default agents vs. custom agents + +Fullsend ships six default agents in +[fullsend-ai/agents](https://github.com/fullsend-ai/agents): triage, +prioritize, code, review, fix, and retro. Each can be configured and extended. +At some point, enough modification turns a configured default agent into a +custom agent that re-uses parts of a default one. + +## Why the distinction matters + +This is a bit of a +[Ship of Theseus](https://en.wikipedia.org/wiki/Ship_of_Theseus) exercise. +The question has a practical purpose, though. We want two things simultaneously: + +1. **Encourage custom agents.** The harness, sandbox, and `base` composition + system exist so teams can build agents tailored to their workflows. +2. **Encourage contribution to default agents.** When a change improves a + default agent for everyone, it should flow upstream rather than live in a + private fork. + +Knowing whether you are running a configured default agent or a custom agent +helps you decide: should this change be contributed back, or does it only make +sense for my team? Clear language helps us all communicate about this. + +**Default to contributing.** If your modification would benefit other users, +contribute it to the default agent's definition. Build a custom agent when +your needs genuinely diverge the default agent's charter. + +## The rule + +> If a modification uses a method documented as a recommended extension point +> for that agent, the result is still a **configured default agent**. If it +> uses any other method, the result is a **custom agent** that re-uses parts +> of a default. + +Each default agent documents its extension points in +[`docs/agents/.md`](../). The review agent, for example, documents +`REVIEW_FINDING_SEVERITY_THRESHOLD` as a configuration variable and +`issue-labels` as an overloadable skill. Using those mechanisms produces a +configured review agent, not a custom one. + +## The `base` lineage test + +The `base` field in a harness YAML +([ADR 0045](../../ADRs/0045-forge-portable-harness-schema.md)) is the first +thing to check. If a harness's `base` chain — through one or more levels of +inheritance — traces back to a default agent harness in `fullsend-ai/fullsend`, +the harness *started from* a default agent. What you override on top of that +base determines whether the result is still a configured default or has crossed +into custom territory. + +If the `base` chain does **not** trace back to a default agent harness, the +agent is custom by definition — regardless of how similar it looks. It is a +custom **from scratch** agent. + +## Classification by harness field + +| Modification | Still a default agent? | Rationale | +|---|---|---| +| Set a documented configuration variable (e.g., `REVIEW_FINDING_SEVERITY_THRESHOLD`) | Yes | Documented extension point. The agent was designed for this. | +| Add environment variables via `env:` | Yes | Env vars augment behavior without changing identity. | +| Add skills via `skills:` | Yes | Skills extend knowledge. The agent's core behavior is unchanged. | +| Add repo-level skills in `.agents/skills/` | Yes | Repo skills are discovered automatically; no harness change needed. | +| Add project instructions via `AGENTS.md` | Yes | All agents read `AGENTS.md`. This is the standard customization path. | +| Override a built-in skill via `customized/skills/` | Yes | Documented extension point ([Customizing with Skills](../../guides/user/customizing-with-skills.md#overriding-built-in-skills)). | +| Replace the sandbox image with one based on the default image | Yes | The agent's behavior is unchanged; the environment is augmented. | +| Add plugins via `plugins:` | Yes | Plugins extend tooling without changing the agent's identity. | +| Add host files via `host_files:` | Yes | Additional data for the sandbox. The agent itself is unchanged. | +| Change the sandbox policy (`policy:`) | Yes | Especially after [PR#2671](https://github.com/fullsend-ai/fullsend/pull/2671) merges, an agent with an augmented policy is arguably still the same agent. | +| **Replace the agent system prompt** (`agent:`) | **Custom** | The system prompt (sometimes called the subagent definition file) provides the primary instructions for the agent. Replacing it creates a different agent. | +| **Replace pre or post scripts** (`pre_script:`, `post_script:`) | **Custom** | Scripts control the agent's integration with external systems. Different scripts mean different behavior at the pipeline boundary. | +| **Replace the app role slug** (`slug:`) | **Custom**\* | The slug determines who the agent authenticates as. A different identity is a different agent. | +| **Replace the validation loop** (`validation_loop:`) | **Custom** | The validation loop defines the contract between the agent and the harness. Changing it changes what the agent is expected to produce. | + +\* Replacing the slug is acceptable in limited cases we may document in the +future — for example, granting the review agent merge rights via a different +GitHub App. When a specific agent's documentation recommends a slug override +for a stated purpose, that override does not make the agent custom. + +## See also + +- [Agents reference](../) — default agent documentation and extension points +- [Customizing agents](../../guides/user/customizing-agents.md) — harness + configuration and layered content resolution +- [Customizing with AGENTS.md](../../guides/user/customizing-with-agents-md.md) + — project-wide instructions for all agents +- [Customizing with skills](../../guides/user/customizing-with-skills.md) — + extending or replacing built-in skills +- [Building custom agents](../../guides/user/building-custom-agents.md) — + creating a new agent from scratch +- [ADR 0045](../../ADRs/0045-forge-portable-harness-schema.md) — `base` + composition and harness inheritance diff --git a/docs/guides/README.md b/docs/guides/README.md index 75dc93433..25c0914ae 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -38,6 +38,7 @@ Guides for developers working in repositories where fullsend is active. - [Customizing with AGENTS.md](user/customizing-with-agents-md.md) — Guide agents using your repo's AGENTS.md file - [Customizing with skills](user/customizing-with-skills.md) — Extend or replace built-in agent skills with custom skill documents - [Building custom agents](user/building-custom-agents.md) — Create a new agent from scratch on a per-repo fullsend installation +- [Default agents vs. custom agents](../agents/topics/default-vs-custom.md) — When customization crosses into custom agent territory ## Development diff --git a/docs/guides/user/building-custom-agents.md b/docs/guides/user/building-custom-agents.md index c32d7b611..8d2e84689 100644 --- a/docs/guides/user/building-custom-agents.md +++ b/docs/guides/user/building-custom-agents.md @@ -8,6 +8,9 @@ This guide walks through creating a new custom agent from scratch on a per-repo fullsend installation. +Not sure whether you need a custom agent or just a configured default agent? +See [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md). + For customizing existing agents (overriding harnesses, skills, or policies), see [Customizing agents](customizing-agents.md). ## Prerequisites diff --git a/docs/guides/user/customizing-agents.md b/docs/guides/user/customizing-agents.md index 99a99e57c..d1990db56 100644 --- a/docs/guides/user/customizing-agents.md +++ b/docs/guides/user/customizing-agents.md @@ -415,6 +415,7 @@ my-repo/ ## See Also +- [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) - When does customization cross into custom agent territory? - [Getting Started](../getting-started/) - Initial setup - [Bugfix Workflow](bugfix-workflow.md) - How agents work together - [Standalone Mint](../infrastructure/standalone-mint.md) - Running your own mint with custom agent roles diff --git a/docs/guides/user/customizing-with-agents-md.md b/docs/guides/user/customizing-with-agents-md.md index 018f31e4b..055fa45ca 100644 --- a/docs/guides/user/customizing-with-agents-md.md +++ b/docs/guides/user/customizing-with-agents-md.md @@ -145,3 +145,8 @@ prompt injection before the agent starts. detailed context in the package directory where it's relevant rather than loading every agent with everything. For example, database migration review checklists belong in `db/migrations/AGENTS.md`, not the root file. + +## See also + +- [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) + — `AGENTS.md` customization keeps you in "configured default agent" territory diff --git a/docs/guides/user/customizing-with-skills.md b/docs/guides/user/customizing-with-skills.md index 83e8e6ae5..d99c11e3f 100644 --- a/docs/guides/user/customizing-with-skills.md +++ b/docs/guides/user/customizing-with-skills.md @@ -163,3 +163,8 @@ apply to all agents and human contributors alike. - **Don't duplicate AGENTS.md content in skills.** If an instruction applies to all agents, put it in `AGENTS.md`. Skills are for agent-specific behavior. + +## See also + +- [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) + — adding skills keeps you in "configured default agent" territory From 8c0c1e290916d7f442dfaf46bb5c09203c2eec49 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Tue, 7 Jul 2026 14:39:04 -0400 Subject: [PATCH 2/7] docs(glossary): add default agent, configured default agent, custom agent Three new glossary entries that codify the terminology from the default-vs-custom doc, with cross-links. Assisted-by: Claude claude-opus-4-6 Signed-off-by: Ralph Bean --- docs/glossary.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index 54623f7b5..9c7dad0eb 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -35,8 +35,25 @@ See [autonomy-spectrum.md](problems/autonomy-spectrum.md). The scope of damage a compromised or misbehaving agent can cause. A core design constraint: every architectural decision about sandboxing, identity scoping, and network policy is evaluated by asking "what is the blast radius if this agent is compromised?" Minimizing blast radius is the primary goal of the sandbox layer. See [security-threat-model.md](problems/security-threat-model.md) and [architecture.md](architecture.md). +## C + +### Configured Default Agent + +A [default agent](#default-agent) whose behavior has been adjusted using only the extension points documented for that agent — environment variables, skills, `AGENTS.md` instructions, sandbox image layers, plugins, or host files. The agent's identity (system prompt, scripts, slug, validation loop) is unchanged; it is still recognizably the same default agent. +See [Default agents vs. custom agents](agents/topics/default-vs-custom.md). + +### Custom Agent + +An agent whose definition diverges from the default agents in ways beyond documented extension points — typically by replacing the system prompt, pre/post scripts, slug, or validation loop. A custom agent may use `base` inheritance to re-use parts of a default agent, but the modifications change the agent's identity. An agent whose `base` chain does not trace back to a default agent harness in `fullsend-ai/fullsend` is custom by definition. +See [Default agents vs. custom agents](agents/topics/default-vs-custom.md) and [Building custom agents](guides/user/building-custom-agents.md). + ## D +### Default Agent + +One of the six agents shipped by fullsend: triage, prioritize, code, review, fix, and retro. Default agents are defined by harness files in `fullsend-ai/fullsend` and agent definitions in `fullsend-ai/agents`. A default agent remains a default agent when customized through its documented extension points (becoming a [configured default agent](#configured-default-agent)); it becomes a [custom agent](#custom-agent) when modifications go beyond those points. +See [Agents reference](agents/) and [Default agents vs. custom agents](agents/topics/default-vs-custom.md). + ### Debouncing Collapsing rapid-fire events on the same issue or PR into a single agent invocation. Without debouncing, a burst of edits to an issue body could trigger multiple redundant triage runs. The [webhook + dispatch service](ADRs/0002-initial-fullsend-design.md#1-webhook--dispatch-service) is responsible for deduplicating flapping events before dispatching work to agents. On GitHub this uses real-time webhooks; on GitLab the cron poller provides watermark-based deduplication at 5–60 minute intervals, which is functionally analogous but operates on a coarser time scale (see [ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). From 1e16ff48e1d3a7115cbbc36a71c173187d4beec2 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Tue, 7 Jul 2026 15:03:43 -0400 Subject: [PATCH 3/7] docs(glossary): differentiate custom-extending-default from custom-from-scratch Split the custom agent glossary entry into two sub-types: custom agents that extend a default beyond its documented extension points, and custom from-scratch agents with no base lineage. Assisted-by: Claude claude-opus-4-6 Signed-off-by: Ralph Bean --- docs/glossary.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/glossary.md b/docs/glossary.md index 9c7dad0eb..1c7b934b5 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -44,7 +44,11 @@ See [Default agents vs. custom agents](agents/topics/default-vs-custom.md). ### Custom Agent -An agent whose definition diverges from the default agents in ways beyond documented extension points — typically by replacing the system prompt, pre/post scripts, slug, or validation loop. A custom agent may use `base` inheritance to re-use parts of a default agent, but the modifications change the agent's identity. An agent whose `base` chain does not trace back to a default agent harness in `fullsend-ai/fullsend` is custom by definition. +An agent that is not a [configured default agent](#configured-default-agent). There are two kinds: + +1. **Custom agent extending a default** — uses `base` inheritance from a default agent harness but replaces identity-defining components (system prompt, pre/post scripts, slug, or validation loop) beyond the documented extension points. It re-uses parts of a default agent but is no longer recognizably that agent. +2. **Custom from-scratch agent** — its `base` chain does not trace back to a default agent harness in `fullsend-ai/fullsend`, or it has no `base` at all. It is built independently, even if it happens to resemble a default agent. + See [Default agents vs. custom agents](agents/topics/default-vs-custom.md) and [Building custom agents](guides/user/building-custom-agents.md). ## D From cb0f38e196a68684d998e073e9185000ac0a2d45 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Tue, 7 Jul 2026 15:04:27 -0400 Subject: [PATCH 4/7] docs(custom-agents): rename to "from scratch", suggest extending defaults first Rename building-custom-agents.md to clarify it covers from-scratch agents. Add a paragraph suggesting base inheritance from a default agent as an alternative before committing to a full custom build. Assisted-by: Claude claude-opus-4-6 Signed-off-by: Ralph Bean --- docs/guides/README.md | 2 +- docs/guides/user/building-custom-agents.md | 12 ++++++++---- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/guides/README.md b/docs/guides/README.md index 25c0914ae..ad82788d4 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -37,7 +37,7 @@ Guides for developers working in repositories where fullsend is active. - [Customizing agents](user/customizing-agents.md) — Harness configurations and layered content resolution for your org and repos - [Customizing with AGENTS.md](user/customizing-with-agents-md.md) — Guide agents using your repo's AGENTS.md file - [Customizing with skills](user/customizing-with-skills.md) — Extend or replace built-in agent skills with custom skill documents -- [Building custom agents](user/building-custom-agents.md) — Create a new agent from scratch on a per-repo fullsend installation +- [Building custom agents from scratch](user/building-custom-agents.md) — Create a new agent from scratch on a per-repo fullsend installation - [Default agents vs. custom agents](../agents/topics/default-vs-custom.md) — When customization crosses into custom agent territory ## Development diff --git a/docs/guides/user/building-custom-agents.md b/docs/guides/user/building-custom-agents.md index 8d2e84689..11b954d93 100644 --- a/docs/guides/user/building-custom-agents.md +++ b/docs/guides/user/building-custom-agents.md @@ -1,4 +1,4 @@ -# Building custom agents +# Building custom agents from scratch > **Deprecated:** This guide uses the `customized/` directory overlay, which is > deprecated per [ADR-0064](../../ADRs/0064-deprecate-customized-directory-overlay.md). @@ -6,10 +6,14 @@ > path instead. Run `fullsend agent migrate-customizations --dry-run` to > preview migrating existing customizations. -This guide walks through creating a new custom agent from scratch on a per-repo fullsend installation. +This guide walks through creating a custom from-scratch agent on a per-repo +fullsend installation. -Not sure whether you need a custom agent or just a configured default agent? -See [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md). +Before building from scratch, consider whether extending a default agent would +meet your needs. You can use `base` inheritance to start from a default agent's +harness and override only what differs — see +[Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) +for the distinction and when each approach makes sense. For customizing existing agents (overriding harnesses, skills, or policies), see [Customizing agents](customizing-agents.md). From a0b711c5c8fc7adaa84e82d2d956a44b4d667f07 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 8 Jul 2026 10:55:28 -0400 Subject: [PATCH 5/7] docs: introduce 'derived agent' tier between configured default and custom MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review feedback from durandom on PR #3398: - Fix typo: "diverge the" → "diverge from the" - Update stale PR#2671 reference (now merged) to past tense - Introduce "derived agent" as distinct terminology for agents that extend a default beyond its documented extension points, replacing the overloaded "custom agent extending a default" phrasing - State the three-tier taxonomy (configured default / derived / custom) up front in the doc for clarity - Update glossary entries and all cross-references Signed-off-by: Ralph Bean Assisted-by: Claude Opus 4.6 Signed-off-by: Ralph Bean --- docs/agents/README.md | 2 +- docs/agents/topics/default-vs-custom.md | 70 +++++++++++-------- docs/glossary.md | 15 ++-- docs/guides/README.md | 2 +- docs/guides/user/building-custom-agents.md | 2 +- docs/guides/user/customizing-agents.md | 2 +- .../guides/user/customizing-with-agents-md.md | 2 +- docs/guides/user/customizing-with-skills.md | 2 +- 8 files changed, 54 insertions(+), 43 deletions(-) diff --git a/docs/agents/README.md b/docs/agents/README.md index 500e4ceda..eb7f5b2ee 100644 --- a/docs/agents/README.md +++ b/docs/agents/README.md @@ -24,7 +24,7 @@ a specific agent performs a specific task. See [Customizing with Skills](../guides/user/customizing-with-skills.md). At some point, enough customization turns a configured default agent into a -custom agent. See [Default agents vs. custom agents](topics/default-vs-custom.md) +derived agent. See [Default, derived, and custom agents](topics/default-vs-custom.md) for where that line is and why it matters. ## Custom Agents diff --git a/docs/agents/topics/default-vs-custom.md b/docs/agents/topics/default-vs-custom.md index d690be025..f2215c098 100644 --- a/docs/agents/topics/default-vs-custom.md +++ b/docs/agents/topics/default-vs-custom.md @@ -1,10 +1,20 @@ -# Default agents vs. custom agents +# Default, derived, and custom agents Fullsend ships six default agents in [fullsend-ai/agents](https://github.com/fullsend-ai/agents): triage, prioritize, code, review, fix, and retro. Each can be configured and extended. -At some point, enough modification turns a configured default agent into a -custom agent that re-uses parts of a default one. +At some point, enough modification turns a configured default into something +different. This document defines three tiers: + +1. **Configured default agent** — uses only documented extension points + (env vars, skills, `AGENTS.md`, plugins, host files, sandbox image layers). + Still recognizably the same default agent. +2. **Derived agent** — starts from a default via `base` inheritance but + replaces identity-defining components (system prompt, scripts, slug, or + validation loop). It re-uses parts of a default but is no longer + recognizably that agent. +3. **Custom agent** — its `base` chain does not trace back to a default agent + harness, or it has no `base` at all. Built from scratch. ## Why the distinction matters @@ -12,32 +22,33 @@ This is a bit of a [Ship of Theseus](https://en.wikipedia.org/wiki/Ship_of_Theseus) exercise. The question has a practical purpose, though. We want two things simultaneously: -1. **Encourage custom agents.** The harness, sandbox, and `base` composition - system exist so teams can build agents tailored to their workflows. +1. **Encourage derived and custom agents.** The harness, sandbox, and `base` + composition system exist so teams can build agents tailored to their + workflows. 2. **Encourage contribution to default agents.** When a change improves a default agent for everyone, it should flow upstream rather than live in a private fork. -Knowing whether you are running a configured default agent or a custom agent -helps you decide: should this change be contributed back, or does it only make -sense for my team? Clear language helps us all communicate about this. +Knowing whether you are running a derived agent or a custom agent helps you +decide: should this change be contributed back, or does it only make sense for +my team? Clear language helps us all communicate about this. **Default to contributing.** If your modification would benefit other users, contribute it to the default agent's definition. Build a custom agent when -your needs genuinely diverge the default agent's charter. +your needs genuinely diverge from the default agent's charter. ## The rule > If a modification uses a method documented as a recommended extension point > for that agent, the result is still a **configured default agent**. If it -> uses any other method, the result is a **custom agent** that re-uses parts +> uses any other method, the result is a **derived agent** that re-uses parts > of a default. Each default agent documents its extension points in [`docs/agents/.md`](../). The review agent, for example, documents `REVIEW_FINDING_SEVERITY_THRESHOLD` as a configuration variable and `issue-labels` as an overloadable skill. Using those mechanisms produces a -configured review agent, not a custom one. +configured review agent, not a derived one. ## The `base` lineage test @@ -47,35 +58,34 @@ thing to check. If a harness's `base` chain — through one or more levels of inheritance — traces back to a default agent harness in `fullsend-ai/fullsend`, the harness *started from* a default agent. What you override on top of that base determines whether the result is still a configured default or has crossed -into custom territory. +into derived territory. If the `base` chain does **not** trace back to a default agent harness, the -agent is custom by definition — regardless of how similar it looks. It is a -custom **from scratch** agent. +agent is custom by definition — regardless of how similar it looks. ## Classification by harness field -| Modification | Still a default agent? | Rationale | +| Modification | Classification | Rationale | |---|---|---| -| Set a documented configuration variable (e.g., `REVIEW_FINDING_SEVERITY_THRESHOLD`) | Yes | Documented extension point. The agent was designed for this. | -| Add environment variables via `env:` | Yes | Env vars augment behavior without changing identity. | -| Add skills via `skills:` | Yes | Skills extend knowledge. The agent's core behavior is unchanged. | -| Add repo-level skills in `.agents/skills/` | Yes | Repo skills are discovered automatically; no harness change needed. | -| Add project instructions via `AGENTS.md` | Yes | All agents read `AGENTS.md`. This is the standard customization path. | -| Override a built-in skill via `customized/skills/` | Yes | Documented extension point ([Customizing with Skills](../../guides/user/customizing-with-skills.md#overriding-built-in-skills)). | -| Replace the sandbox image with one based on the default image | Yes | The agent's behavior is unchanged; the environment is augmented. | -| Add plugins via `plugins:` | Yes | Plugins extend tooling without changing the agent's identity. | -| Add host files via `host_files:` | Yes | Additional data for the sandbox. The agent itself is unchanged. | -| Change the sandbox policy (`policy:`) | Yes | Especially after [PR#2671](https://github.com/fullsend-ai/fullsend/pull/2671) merges, an agent with an augmented policy is arguably still the same agent. | -| **Replace the agent system prompt** (`agent:`) | **Custom** | The system prompt (sometimes called the subagent definition file) provides the primary instructions for the agent. Replacing it creates a different agent. | -| **Replace pre or post scripts** (`pre_script:`, `post_script:`) | **Custom** | Scripts control the agent's integration with external systems. Different scripts mean different behavior at the pipeline boundary. | -| **Replace the app role slug** (`slug:`) | **Custom**\* | The slug determines who the agent authenticates as. A different identity is a different agent. | -| **Replace the validation loop** (`validation_loop:`) | **Custom** | The validation loop defines the contract between the agent and the harness. Changing it changes what the agent is expected to produce. | +| Set a documented configuration variable (e.g., `REVIEW_FINDING_SEVERITY_THRESHOLD`) | Configured default | Documented extension point. The agent was designed for this. | +| Add environment variables via `env:` | Configured default | Env vars augment behavior without changing identity. | +| Add skills via `skills:` | Configured default | Skills extend knowledge. The agent's core behavior is unchanged. | +| Add repo-level skills in `.agents/skills/` | Configured default | Repo skills are discovered automatically; no harness change needed. | +| Add project instructions via `AGENTS.md` | Configured default | All agents read `AGENTS.md`. This is the standard customization path. | +| Override a built-in skill via `customized/skills/` | Configured default | Documented extension point ([Customizing with Skills](../../guides/user/customizing-with-skills.md#overriding-built-in-skills)). | +| Replace the sandbox image with one based on the default image | Configured default | The agent's behavior is unchanged; the environment is augmented. | +| Add plugins via `plugins:` | Configured default | Plugins extend tooling without changing the agent's identity. | +| Add host files via `host_files:` | Configured default | Additional data for the sandbox. The agent itself is unchanged. | +| Change the sandbox policy (`policy:`) | Configured default | With [policy composition](https://github.com/fullsend-ai/fullsend/pull/2671), an agent with an augmented policy is still the same agent. | +| **Replace the agent system prompt** (`agent:`) | **Derived** | The system prompt (sometimes called the subagent definition file) provides the primary instructions for the agent. Replacing it creates a different agent. | +| **Replace pre or post scripts** (`pre_script:`, `post_script:`) | **Derived** | Scripts control the agent's integration with external systems. Different scripts mean different behavior at the pipeline boundary. | +| **Replace the app role slug** (`slug:`) | **Derived**\* | The slug determines who the agent authenticates as. A different identity is a different agent. | +| **Replace the validation loop** (`validation_loop:`) | **Derived** | The validation loop defines the contract between the agent and the harness. Changing it changes what the agent is expected to produce. | \* Replacing the slug is acceptable in limited cases we may document in the future — for example, granting the review agent merge rights via a different GitHub App. When a specific agent's documentation recommends a slug override -for a stated purpose, that override does not make the agent custom. +for a stated purpose, that override does not make the agent derived. ## See also diff --git a/docs/glossary.md b/docs/glossary.md index 1c7b934b5..30e9b3d4a 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -40,23 +40,24 @@ See [security-threat-model.md](problems/security-threat-model.md) and [architect ### Configured Default Agent A [default agent](#default-agent) whose behavior has been adjusted using only the extension points documented for that agent — environment variables, skills, `AGENTS.md` instructions, sandbox image layers, plugins, or host files. The agent's identity (system prompt, scripts, slug, validation loop) is unchanged; it is still recognizably the same default agent. -See [Default agents vs. custom agents](agents/topics/default-vs-custom.md). +See [Default, derived, and custom agents](agents/topics/default-vs-custom.md). ### Custom Agent -An agent that is not a [configured default agent](#configured-default-agent). There are two kinds: +An agent whose `base` chain does not trace back to a default agent harness in `fullsend-ai/fullsend`, or that has no `base` at all. A custom agent is built from scratch, even if it happens to resemble a default agent. Contrast with [derived agent](#derived-agent), which starts from a default. +See [Default, derived, and custom agents](agents/topics/default-vs-custom.md) and [Building custom agents](guides/user/building-custom-agents.md). -1. **Custom agent extending a default** — uses `base` inheritance from a default agent harness but replaces identity-defining components (system prompt, pre/post scripts, slug, or validation loop) beyond the documented extension points. It re-uses parts of a default agent but is no longer recognizably that agent. -2. **Custom from-scratch agent** — its `base` chain does not trace back to a default agent harness in `fullsend-ai/fullsend`, or it has no `base` at all. It is built independently, even if it happens to resemble a default agent. +### Derived Agent -See [Default agents vs. custom agents](agents/topics/default-vs-custom.md) and [Building custom agents](guides/user/building-custom-agents.md). +An agent that uses `base` inheritance from a default agent harness but replaces identity-defining components (system prompt, pre/post scripts, slug, or validation loop) beyond the documented extension points. It re-uses parts of a default agent but is no longer recognizably that agent. Contrast with [configured default agent](#configured-default-agent) (stays within extension points) and [custom agent](#custom-agent) (built from scratch). +See [Default, derived, and custom agents](agents/topics/default-vs-custom.md). ## D ### Default Agent -One of the six agents shipped by fullsend: triage, prioritize, code, review, fix, and retro. Default agents are defined by harness files in `fullsend-ai/fullsend` and agent definitions in `fullsend-ai/agents`. A default agent remains a default agent when customized through its documented extension points (becoming a [configured default agent](#configured-default-agent)); it becomes a [custom agent](#custom-agent) when modifications go beyond those points. -See [Agents reference](agents/) and [Default agents vs. custom agents](agents/topics/default-vs-custom.md). +One of the six agents shipped by fullsend: triage, prioritize, code, review, fix, and retro. Default agents are defined by harness files in `fullsend-ai/fullsend` and agent definitions in `fullsend-ai/agents`. A default agent remains a default agent when customized through its documented extension points (becoming a [configured default agent](#configured-default-agent)); it becomes a [derived agent](#derived-agent) when modifications go beyond those points. +See [Agents reference](agents/) and [Default, derived, and custom agents](agents/topics/default-vs-custom.md). ### Debouncing diff --git a/docs/guides/README.md b/docs/guides/README.md index ad82788d4..9734fd961 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -38,7 +38,7 @@ Guides for developers working in repositories where fullsend is active. - [Customizing with AGENTS.md](user/customizing-with-agents-md.md) — Guide agents using your repo's AGENTS.md file - [Customizing with skills](user/customizing-with-skills.md) — Extend or replace built-in agent skills with custom skill documents - [Building custom agents from scratch](user/building-custom-agents.md) — Create a new agent from scratch on a per-repo fullsend installation -- [Default agents vs. custom agents](../agents/topics/default-vs-custom.md) — When customization crosses into custom agent territory +- [Default, derived, and custom agents](../agents/topics/default-vs-custom.md) — When customization crosses into derived or custom agent territory ## Development diff --git a/docs/guides/user/building-custom-agents.md b/docs/guides/user/building-custom-agents.md index 11b954d93..2254a852f 100644 --- a/docs/guides/user/building-custom-agents.md +++ b/docs/guides/user/building-custom-agents.md @@ -12,7 +12,7 @@ fullsend installation. Before building from scratch, consider whether extending a default agent would meet your needs. You can use `base` inheritance to start from a default agent's harness and override only what differs — see -[Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) +[Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) for the distinction and when each approach makes sense. For customizing existing agents (overriding harnesses, skills, or policies), see [Customizing agents](customizing-agents.md). diff --git a/docs/guides/user/customizing-agents.md b/docs/guides/user/customizing-agents.md index d1990db56..be5d9250d 100644 --- a/docs/guides/user/customizing-agents.md +++ b/docs/guides/user/customizing-agents.md @@ -415,7 +415,7 @@ my-repo/ ## See Also -- [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) - When does customization cross into custom agent territory? +- [Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) - When does customization cross into derived or custom agent territory? - [Getting Started](../getting-started/) - Initial setup - [Bugfix Workflow](bugfix-workflow.md) - How agents work together - [Standalone Mint](../infrastructure/standalone-mint.md) - Running your own mint with custom agent roles diff --git a/docs/guides/user/customizing-with-agents-md.md b/docs/guides/user/customizing-with-agents-md.md index 055fa45ca..91a97492a 100644 --- a/docs/guides/user/customizing-with-agents-md.md +++ b/docs/guides/user/customizing-with-agents-md.md @@ -148,5 +148,5 @@ prompt injection before the agent starts. ## See also -- [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) +- [Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) — `AGENTS.md` customization keeps you in "configured default agent" territory diff --git a/docs/guides/user/customizing-with-skills.md b/docs/guides/user/customizing-with-skills.md index d99c11e3f..9685809d0 100644 --- a/docs/guides/user/customizing-with-skills.md +++ b/docs/guides/user/customizing-with-skills.md @@ -166,5 +166,5 @@ apply to all agents and human contributors alike. ## See also -- [Default agents vs. custom agents](../../agents/topics/default-vs-custom.md) +- [Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) — adding skills keeps you in "configured default agent" territory From 589d766d328cd5f4e9381f1c9cd4b19c714f5ce4 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 8 Jul 2026 13:04:11 -0400 Subject: [PATCH 6/7] =?UTF-8?q?docs:=20address=20review=20feedback=20?= =?UTF-8?q?=E2=80=94=20terminology=20sweep=20and=20cleanups?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove Ship of Theseus reference (too obscure without explanation) - Remove explicit agent list from intro (will go stale) - Broaden "the rule" to acknowledge general-purpose harness fields alongside documented extension points, resolving the inconsistency between the rule and the classification table - Drop conditional language around policy composition (PR #2671 merged) - Sweep docs/ link text: "Customizing" → "Configuring" for guides about documented extension points, reserving "custom" for from-scratch agents - Update glossary entries to match Assisted-by: Claude Opus 4.6 Signed-off-by: Ralph Bean --- docs/agents/README.md | 10 +++---- docs/agents/code.md | 4 +-- docs/agents/fix.md | 4 +-- docs/agents/retro.md | 4 +-- docs/agents/review.md | 4 +-- docs/agents/topics/default-vs-custom.md | 28 +++++++++---------- docs/glossary.md | 4 +-- docs/guides/README.md | 8 +++--- docs/guides/dev/cli-internals.md | 2 +- .../infrastructure/private-repositories.md | 2 +- docs/guides/user/building-custom-agents.md | 10 +++---- docs/guides/user/customizing-agents.md | 2 +- .../guides/user/customizing-with-agents-md.md | 4 +-- docs/guides/user/customizing-with-skills.md | 2 +- docs/guides/user/running-agents-locally.md | 2 +- 15 files changed, 44 insertions(+), 46 deletions(-) diff --git a/docs/agents/README.md b/docs/agents/README.md index eb7f5b2ee..64fa39425 100644 --- a/docs/agents/README.md +++ b/docs/agents/README.md @@ -15,15 +15,15 @@ config (see [ADR 0058](../ADRs/0058-agent-registration.md)). | [Fix](fix.md) | Addresses review feedback on open PRs | | [Retro](retro.md) | Analyzes completed workflows and proposes system improvements | -## Customization +## Configuration -All agents can be customized by adding instructions and skills to your +All agents can be configured by adding instructions and skills to your repository. Changes to `AGENTS.md` affect every agent; skills let you tune how a specific agent performs a specific task. See -[Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and -[Customizing with Skills](../guides/user/customizing-with-skills.md). +[Configuring with AGENTS.md](../guides/user/customizing-with-agents-md.md) and +[Configuring with Skills](../guides/user/customizing-with-skills.md). -At some point, enough customization turns a configured default agent into a +At some point, enough configuration turns a configured default agent into a derived agent. See [Default, derived, and custom agents](topics/default-vs-custom.md) for where that line is and why it matters. diff --git a/docs/agents/code.md b/docs/agents/code.md index 9bdfd7ffc..669b739fc 100644 --- a/docs/agents/code.md +++ b/docs/agents/code.md @@ -43,8 +43,8 @@ on issues (not PRs). The code agent is also triggered automatically when the ## Configuration and extension -See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and -[Customizing with Skills](../guides/user/customizing-with-skills.md). +See [Configuring with AGENTS.md](../guides/user/customizing-with-agents-md.md) and +[Configuring with Skills](../guides/user/customizing-with-skills.md). ### Variables diff --git a/docs/agents/fix.md b/docs/agents/fix.md index babbbf2a2..d1384a507 100644 --- a/docs/agents/fix.md +++ b/docs/agents/fix.md @@ -132,8 +132,8 @@ Remove the label or use `/fs-fix` to re-engage. ## Configuration and extension -See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and -[Customizing with Skills](../guides/user/customizing-with-skills.md). +See [Configuring with AGENTS.md](../guides/user/customizing-with-agents-md.md) and +[Configuring with Skills](../guides/user/customizing-with-skills.md). ### Variables diff --git a/docs/agents/retro.md b/docs/agents/retro.md index 1cf14dcc8..8bc36dbcb 100644 --- a/docs/agents/retro.md +++ b/docs/agents/retro.md @@ -47,8 +47,8 @@ The retro agent also runs automatically when a PR is closed (merged or not). ## Configuration and extension -See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and -[Customizing with Skills](../guides/user/customizing-with-skills.md). +See [Configuring with AGENTS.md](../guides/user/customizing-with-agents-md.md) and +[Configuring with Skills](../guides/user/customizing-with-skills.md). ### Variables diff --git a/docs/agents/review.md b/docs/agents/review.md index b9a90260e..af420f35e 100644 --- a/docs/agents/review.md +++ b/docs/agents/review.md @@ -72,8 +72,8 @@ the upstream default -- no other configuration needed. > config-driven agent registration instead. Run `fullsend agent migrate-customizations` > to migrate existing overrides. -See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and -[Customizing with Skills](../guides/user/customizing-with-skills.md). +See [Configuring with AGENTS.md](../guides/user/customizing-with-agents-md.md) and +[Configuring with Skills](../guides/user/customizing-with-skills.md). ### Variables diff --git a/docs/agents/topics/default-vs-custom.md b/docs/agents/topics/default-vs-custom.md index f2215c098..bf880993e 100644 --- a/docs/agents/topics/default-vs-custom.md +++ b/docs/agents/topics/default-vs-custom.md @@ -1,8 +1,8 @@ # Default, derived, and custom agents -Fullsend ships six default agents in -[fullsend-ai/agents](https://github.com/fullsend-ai/agents): triage, -prioritize, code, review, fix, and retro. Each can be configured and extended. +Fullsend ships a set of default agents in +[fullsend-ai/agents](https://github.com/fullsend-ai/agents). Each can be +configured and extended. At some point, enough modification turns a configured default into something different. This document defines three tiers: @@ -18,9 +18,7 @@ different. This document defines three tiers: ## Why the distinction matters -This is a bit of a -[Ship of Theseus](https://en.wikipedia.org/wiki/Ship_of_Theseus) exercise. -The question has a practical purpose, though. We want two things simultaneously: +We want two things simultaneously: 1. **Encourage derived and custom agents.** The harness, sandbox, and `base` composition system exist so teams can build agents tailored to their @@ -39,10 +37,10 @@ your needs genuinely diverge from the default agent's charter. ## The rule -> If a modification uses a method documented as a recommended extension point -> for that agent, the result is still a **configured default agent**. If it -> uses any other method, the result is a **derived agent** that re-uses parts -> of a default. +> If a modification uses a documented extension point for that agent, or a +> general-purpose harness field that does not alter the agent's identity, the +> result is still a **configured default agent**. If it replaces +> identity-defining components, the result is a **derived agent**. Each default agent documents its extension points in [`docs/agents/.md`](../). The review agent, for example, documents @@ -72,11 +70,11 @@ agent is custom by definition — regardless of how similar it looks. | Add skills via `skills:` | Configured default | Skills extend knowledge. The agent's core behavior is unchanged. | | Add repo-level skills in `.agents/skills/` | Configured default | Repo skills are discovered automatically; no harness change needed. | | Add project instructions via `AGENTS.md` | Configured default | All agents read `AGENTS.md`. This is the standard customization path. | -| Override a built-in skill via `customized/skills/` | Configured default | Documented extension point ([Customizing with Skills](../../guides/user/customizing-with-skills.md#overriding-built-in-skills)). | +| Override a built-in skill via `customized/skills/` | Configured default | Documented extension point ([Configuring with Skills](../../guides/user/customizing-with-skills.md#overriding-built-in-skills)). | | Replace the sandbox image with one based on the default image | Configured default | The agent's behavior is unchanged; the environment is augmented. | | Add plugins via `plugins:` | Configured default | Plugins extend tooling without changing the agent's identity. | | Add host files via `host_files:` | Configured default | Additional data for the sandbox. The agent itself is unchanged. | -| Change the sandbox policy (`policy:`) | Configured default | With [policy composition](https://github.com/fullsend-ai/fullsend/pull/2671), an agent with an augmented policy is still the same agent. | +| Change the sandbox policy (`policy:`) | Configured default | Policy composition lets you augment an agent's policy without changing its identity. | | **Replace the agent system prompt** (`agent:`) | **Derived** | The system prompt (sometimes called the subagent definition file) provides the primary instructions for the agent. Replacing it creates a different agent. | | **Replace pre or post scripts** (`pre_script:`, `post_script:`) | **Derived** | Scripts control the agent's integration with external systems. Different scripts mean different behavior at the pipeline boundary. | | **Replace the app role slug** (`slug:`) | **Derived**\* | The slug determines who the agent authenticates as. A different identity is a different agent. | @@ -90,11 +88,11 @@ for a stated purpose, that override does not make the agent derived. ## See also - [Agents reference](../) — default agent documentation and extension points -- [Customizing agents](../../guides/user/customizing-agents.md) — harness +- [Configuring agents](../../guides/user/customizing-agents.md) — harness configuration and layered content resolution -- [Customizing with AGENTS.md](../../guides/user/customizing-with-agents-md.md) +- [Configuring with AGENTS.md](../../guides/user/customizing-with-agents-md.md) — project-wide instructions for all agents -- [Customizing with skills](../../guides/user/customizing-with-skills.md) — +- [Configuring with skills](../../guides/user/customizing-with-skills.md) — extending or replacing built-in skills - [Building custom agents](../../guides/user/building-custom-agents.md) — creating a new agent from scratch diff --git a/docs/glossary.md b/docs/glossary.md index 30e9b3d4a..0aa066487 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -39,7 +39,7 @@ See [security-threat-model.md](problems/security-threat-model.md) and [architect ### Configured Default Agent -A [default agent](#default-agent) whose behavior has been adjusted using only the extension points documented for that agent — environment variables, skills, `AGENTS.md` instructions, sandbox image layers, plugins, or host files. The agent's identity (system prompt, scripts, slug, validation loop) is unchanged; it is still recognizably the same default agent. +A [default agent](#default-agent) whose behavior has been adjusted using documented extension points or general-purpose harness fields that do not alter the agent's identity — environment variables, skills, `AGENTS.md` instructions, sandbox image layers, plugins, or host files. The agent's identity (system prompt, scripts, slug, validation loop) is unchanged; it is still recognizably the same default agent. See [Default, derived, and custom agents](agents/topics/default-vs-custom.md). ### Custom Agent @@ -56,7 +56,7 @@ See [Default, derived, and custom agents](agents/topics/default-vs-custom.md). ### Default Agent -One of the six agents shipped by fullsend: triage, prioritize, code, review, fix, and retro. Default agents are defined by harness files in `fullsend-ai/fullsend` and agent definitions in `fullsend-ai/agents`. A default agent remains a default agent when customized through its documented extension points (becoming a [configured default agent](#configured-default-agent)); it becomes a [derived agent](#derived-agent) when modifications go beyond those points. +An agent shipped by fullsend, defined by harness files in `fullsend-ai/fullsend` and agent definitions in `fullsend-ai/agents`. A default agent remains a default agent when configured through its documented extension points (becoming a [configured default agent](#configured-default-agent)); it becomes a [derived agent](#derived-agent) when modifications go beyond those points. See [Agents reference](agents/) and [Default, derived, and custom agents](agents/topics/default-vs-custom.md). ### Debouncing diff --git a/docs/guides/README.md b/docs/guides/README.md index 9734fd961..0b14a7ab8 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -34,11 +34,11 @@ Guides for developers working in repositories where fullsend is active. - [Bugfix workflow](user/bugfix-workflow.md) — End-to-end guide to how fullsend handles a bug report from issue to merge - [Running agents locally](user/running-agents-locally.md) — Run fullsend agents on your machine using released binaries (macOS + Linux) -- [Customizing agents](user/customizing-agents.md) — Harness configurations and layered content resolution for your org and repos -- [Customizing with AGENTS.md](user/customizing-with-agents-md.md) — Guide agents using your repo's AGENTS.md file -- [Customizing with skills](user/customizing-with-skills.md) — Extend or replace built-in agent skills with custom skill documents +- [Configuring agents](user/customizing-agents.md) — Harness configurations and layered content resolution for your org and repos +- [Configuring with AGENTS.md](user/customizing-with-agents-md.md) — Guide agents using your repo's AGENTS.md file +- [Configuring with skills](user/customizing-with-skills.md) — Extend or replace built-in agent skills with custom skill documents - [Building custom agents from scratch](user/building-custom-agents.md) — Create a new agent from scratch on a per-repo fullsend installation -- [Default, derived, and custom agents](../agents/topics/default-vs-custom.md) — When customization crosses into derived or custom agent territory +- [Default, derived, and custom agents](../agents/topics/default-vs-custom.md) — When configuration crosses into derived or custom agent territory ## Development diff --git a/docs/guides/dev/cli-internals.md b/docs/guides/dev/cli-internals.md index 849d35495..70113a34d 100644 --- a/docs/guides/dev/cli-internals.md +++ b/docs/guides/dev/cli-internals.md @@ -603,4 +603,4 @@ var executableFiles = map[string]struct{}{ - [Advanced setup](../infrastructure/advanced-setup.md) — Alternative installation paths and setup flags - [Mint service administration](../infrastructure/mint-administration.md) — Deploying and managing the token mint - [Infrastructure Reference](../infrastructure/infrastructure-reference.md) — Infrastructure details -- [Customizing Agents](../user/customizing-agents.md) — User customization guide +- [Configuring Agents](../user/customizing-agents.md) — User configuration guide diff --git a/docs/guides/infrastructure/private-repositories.md b/docs/guides/infrastructure/private-repositories.md index 043ce30df..3f9c4b69f 100644 --- a/docs/guides/infrastructure/private-repositories.md +++ b/docs/guides/infrastructure/private-repositories.md @@ -194,6 +194,6 @@ Not all private repos are equal. A repo containing open-source code that happens ## See also - [Getting Started](../getting-started/) — Initial fullsend setup -- [Customizing agents](../user/customizing-agents.md) — Harness configuration and layered overrides +- [Configuring agents](../user/customizing-agents.md) — Harness configuration and layered overrides - [Security threat model](../../problems/security-threat-model.md) — Threat priority and defense considerations - [#1189](https://github.com/fullsend-ai/fullsend/issues/1189) — Retro agent private content leak risk diff --git a/docs/guides/user/building-custom-agents.md b/docs/guides/user/building-custom-agents.md index 2254a852f..a34ac31f0 100644 --- a/docs/guides/user/building-custom-agents.md +++ b/docs/guides/user/building-custom-agents.md @@ -15,7 +15,7 @@ harness and override only what differs — see [Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) for the distinction and when each approach makes sense. -For customizing existing agents (overriding harnesses, skills, or policies), see [Customizing agents](customizing-agents.md). +For configuring existing agents (overriding harnesses, skills, or policies), see [Configuring agents](customizing-agents.md). ## Prerequisites @@ -35,7 +35,7 @@ A custom agent is composed of six parts: skills/ # Knowledge documents mounted into the sandbox ``` -At build time, the workflow layers these customized files on top of the upstream fullsend defaults. Your files override the defaults — anything you don't customize uses the standard fullsend configuration. See [Customizing agents — Layered Configuration Resolution](customizing-agents.md#layered-configuration-resolution) for details on how the layering works. +At build time, the workflow layers these customized files on top of the upstream fullsend defaults. Your files override the defaults — anything you don't customize uses the standard fullsend configuration. See [Configuring agents — Layered Configuration Resolution](customizing-agents.md#layered-configuration-resolution) for details on how the layering works. The key security invariant: agents run inside an untrusted [sandbox](../../glossary.md#sandbox) with no credentials. Pre-scripts fetch data *before* the sandbox starts; post-scripts act on agent output *after* the sandbox exits. Agents never have direct write access to external systems. See the [security threat model](../../problems/security-threat-model.md) for the full trust model. @@ -183,7 +183,7 @@ timeout_minutes: 20 # max_runtime_fetches: 10 ``` -See [Customizing agents — Harness YAML Structure](customizing-agents.md#harness-yaml-structure) for the full field reference (including optional `security`, `providers`, `plugins`, and runtime fetch blocks). +See [Configuring agents — Harness YAML Structure](customizing-agents.md#harness-yaml-structure) for the full field reference (including optional `security`, `providers`, `plugins`, and runtime fetch blocks). The key pattern to understand is how data flows into the sandbox through `host_files`: @@ -375,7 +375,7 @@ The post-script runs on the trusted runner with full credentials, but reads outp ## Step 6: Create skills (optional) -[Skills](../../glossary.md#skill) are Markdown documents mounted into the sandbox that provide domain knowledge the agent can reference. See [Customizing agents — Adding a Custom Skill](customizing-agents.md#adding-a-custom-skill) for how to create one. +[Skills](../../glossary.md#skill) are Markdown documents mounted into the sandbox that provide domain knowledge the agent can reference. See [Configuring agents — Adding a Custom Skill](customizing-agents.md#adding-a-custom-skill) for how to create one. Place your skill at `.fullsend/customized/skills/my-skill/SKILL.md`, then reference it in both the agent frontmatter (`skills: [my-skill]`) and the harness (`skills: [customized/skills/my-skill]`). @@ -626,7 +626,7 @@ When creating a new agent, you need these files: ## Reference -- [Customizing agents](customizing-agents.md) — override existing agent harnesses, skills, and policies +- [Configuring agents](customizing-agents.md) — override existing agent harnesses, skills, and policies - [Bugfix workflow](bugfix-workflow.md) — how the built-in agents work together end to end - [Getting Started](../getting-started/README.md) — prerequisite: admin setup guide - [Architecture overview](../../architecture.md) — component vocabulary and execution stack diff --git a/docs/guides/user/customizing-agents.md b/docs/guides/user/customizing-agents.md index be5d9250d..e20772005 100644 --- a/docs/guides/user/customizing-agents.md +++ b/docs/guides/user/customizing-agents.md @@ -415,7 +415,7 @@ my-repo/ ## See Also -- [Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) - When does customization cross into derived or custom agent territory? +- [Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) - When does configuration cross into derived or custom agent territory? - [Getting Started](../getting-started/) - Initial setup - [Bugfix Workflow](bugfix-workflow.md) - How agents work together - [Standalone Mint](../infrastructure/standalone-mint.md) - Running your own mint with custom agent roles diff --git a/docs/guides/user/customizing-with-agents-md.md b/docs/guides/user/customizing-with-agents-md.md index 91a97492a..15b9cc120 100644 --- a/docs/guides/user/customizing-with-agents-md.md +++ b/docs/guides/user/customizing-with-agents-md.md @@ -6,7 +6,7 @@ read its `AGENTS.md` file — the same file human contributors use. No fullsend configuration changes needed. For agent-specific customization using skills, see -[Customizing with Skills](customizing-with-skills.md). +[Configuring with Skills](customizing-with-skills.md). ## What to put in AGENTS.md @@ -149,4 +149,4 @@ prompt injection before the agent starts. ## See also - [Default, derived, and custom agents](../../agents/topics/default-vs-custom.md) - — `AGENTS.md` customization keeps you in "configured default agent" territory + — `AGENTS.md` configuration keeps you in "configured default agent" territory diff --git a/docs/guides/user/customizing-with-skills.md b/docs/guides/user/customizing-with-skills.md index 9685809d0..30dc45ecd 100644 --- a/docs/guides/user/customizing-with-skills.md +++ b/docs/guides/user/customizing-with-skills.md @@ -6,7 +6,7 @@ default agent ships with built-in skills, and you can extend or replace them by committing your own skills to your repository. For general project-wide instructions (code style, test conventions, -architecture rules), see [Customizing with AGENTS.md](customizing-with-agents-md.md). +architecture rules), see [Configuring with AGENTS.md](customizing-with-agents-md.md). This guide covers skills specifically. ## What is a skill? diff --git a/docs/guides/user/running-agents-locally.md b/docs/guides/user/running-agents-locally.md index 7f2a3fb4e..afa741ef3 100644 --- a/docs/guides/user/running-agents-locally.md +++ b/docs/guides/user/running-agents-locally.md @@ -105,7 +105,7 @@ git clone git@github:{org}/{target_repository} /tmp/target-repo Next clone the repository where the agent lives, in this guide case you need to clone Fullsend's repository. To learn more about custom agents visit -[Customizing Agents](customizing-agents.md). +[Configuring Agents](customizing-agents.md). ```bash git clone --depth 1 https://github.com/fullsend-ai/fullsend.git /tmp/fullsend-ai_fullsend/ From 32f8fe5afaf7a3cff9d827c106e5292977b9bca1 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 8 Jul 2026 14:03:24 -0400 Subject: [PATCH 7/7] docs(glossary): move Derived Agent to section D, alphabetize Assisted-by: Claude Opus 4.6 Signed-off-by: Ralph Bean --- docs/glossary.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 0aa066487..1c8130a70 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -47,22 +47,22 @@ See [Default, derived, and custom agents](agents/topics/default-vs-custom.md). An agent whose `base` chain does not trace back to a default agent harness in `fullsend-ai/fullsend`, or that has no `base` at all. A custom agent is built from scratch, even if it happens to resemble a default agent. Contrast with [derived agent](#derived-agent), which starts from a default. See [Default, derived, and custom agents](agents/topics/default-vs-custom.md) and [Building custom agents](guides/user/building-custom-agents.md). -### Derived Agent +## D -An agent that uses `base` inheritance from a default agent harness but replaces identity-defining components (system prompt, pre/post scripts, slug, or validation loop) beyond the documented extension points. It re-uses parts of a default agent but is no longer recognizably that agent. Contrast with [configured default agent](#configured-default-agent) (stays within extension points) and [custom agent](#custom-agent) (built from scratch). -See [Default, derived, and custom agents](agents/topics/default-vs-custom.md). +### Debouncing -## D +Collapsing rapid-fire events on the same issue or PR into a single agent invocation. Without debouncing, a burst of edits to an issue body could trigger multiple redundant triage runs. The [webhook + dispatch service](ADRs/0002-initial-fullsend-design.md#1-webhook--dispatch-service) is responsible for deduplicating flapping events before dispatching work to agents. On GitHub this uses real-time webhooks; on GitLab the cron poller provides watermark-based deduplication at 5–60 minute intervals, which is functionally analogous but operates on a coarser time scale (see [ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). +See [architecture.md](architecture.md) (building block 1). ### Default Agent An agent shipped by fullsend, defined by harness files in `fullsend-ai/fullsend` and agent definitions in `fullsend-ai/agents`. A default agent remains a default agent when configured through its documented extension points (becoming a [configured default agent](#configured-default-agent)); it becomes a [derived agent](#derived-agent) when modifications go beyond those points. See [Agents reference](agents/) and [Default, derived, and custom agents](agents/topics/default-vs-custom.md). -### Debouncing +### Derived Agent -Collapsing rapid-fire events on the same issue or PR into a single agent invocation. Without debouncing, a burst of edits to an issue body could trigger multiple redundant triage runs. The [webhook + dispatch service](ADRs/0002-initial-fullsend-design.md#1-webhook--dispatch-service) is responsible for deduplicating flapping events before dispatching work to agents. On GitHub this uses real-time webhooks; on GitLab the cron poller provides watermark-based deduplication at 5–60 minute intervals, which is functionally analogous but operates on a coarser time scale (see [ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)). -See [architecture.md](architecture.md) (building block 1). +An agent that uses `base` inheritance from a default agent harness but replaces identity-defining components (system prompt, pre/post scripts, slug, or validation loop) beyond the documented extension points. It re-uses parts of a default agent but is no longer recognizably that agent. Contrast with [configured default agent](#configured-default-agent) (stays within extension points) and [custom agent](#custom-agent) (built from scratch). +See [Default, derived, and custom agents](agents/topics/default-vs-custom.md). ## E