docs(glossary): customization vocabulary for agents and skills

[ascerra]

Summary

• Adds a Customization vocabulary section and related A–Z glossary entries for agent classification (default / configured default / derived / custom), skills (additive, override, always-on, on-demand, repo, built-in), and script overrides.
• Aligns default-vs-custom.md with fullsend-ai/agents harness lineage and “categories” wording (not bare “tiers”).
• Does not ship the abandoned always-on ADR (metadata.apply / soft Skill directive). Always-on / on-demand glossary entries point at #6681 / #6682 / #6859 instead. Former stack base #6378 was closed unmerged.

Test plan

• Rebased onto main (includes merged #6459 OTEL score export glossary text)
• No duplicate ADR 0092; openai-wif 0092 untouched
• Markdown link lint / ADR number lint clean on commit
• Spot-check glossary Always-on / On-demand Planned banners vs feat(#6681): inject harness skills into agent frontmatter for always-on activation #6859 when it merges

[github-actions]

Site preview

Preview: https://d5e023c6-site.fullsend-ai.workers.dev

Commit: 5416809cf3a34ddc40ce62635bafd9425a1198c9

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:11 PM UTC · Completed 4:28 PM UTC

Commit: c6ab34e · View workflow run →

[fullsend-ai-review]

Review

Findings

Low

• [incorrect-doc] docs/agents/triage.md:100 — docs/agents/triage.md (line 100) and docs/agents/review.md (lines 70–71) still tell users to override the built-in issue-labels skill by dropping .agents/skills/issue-labels/SKILL.md and symlinking .claude/skills. That path is shadowed under Claude Code's personal-over-project precedence, which this PR now states as canonical vocabulary (Repo Skill / Skill Override), and which docs/guides/user/customizing-with-skills.md#overriding-built-in-skills already documents as the supported override. Pre-existing contradiction in files this PR does not touch — not a blocker for this PR.
  Remediation: In a follow-up, update docs/agents/triage.md and docs/agents/review.md to drop the .agents/skills/issue-labels drop-in override instructions and point at config-driven / base: harness composition per docs/guides/user/customizing-with-skills.md#overriding-built-in-skills.

• [stale-doc] docs/agents/topics/escalation-ladder.md:111 — The Level 3 example still uses a base: URL under fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/code.yaml, and lines 80–84 still describe default harnesses/definitions as living in fullsend-ai/fullsend. This PR updates the identical harness-lineage reference in the sibling file default-vs-custom.md and the glossary to fullsend-ai/agents, leaving this untouched, "Status: Proposed" file with the old path. Pre-existing issue, not introduced by this PR.
  Remediation: In a follow-up, update the Level 3 example URL to point at fullsend-ai/agents/<sha>/harness/code.yaml and align lines 80–84 with fullsend-ai/agents as the home of default harnesses, definitions, and built-in skills.

Previous run

Review

Findings

Medium

• [internal-inconsistency] docs/glossary.md:108 — Configured Default Agent and Derived Agent list identity-defining fields as agent:, pre-script/post-script, slug, and validation loop, treating a slug change as derived (unless docs recommend an override) and omitting role:. That contradicts the classification table in docs/agents/topics/default-vs-custom.md (touched in this same PR): slug: is install-time-only / configured default (the mint never reads it), and role: is Derived* (documented-exception footnote). The role-override exception appears to have been misapplied to slug in the glossary.
  Remediation: Align both glossary entries with the Classification-by-harness-field table: identity-defining fields are agent:, pre_script/post_script, role: (with the documented-exception footnote), and validation_loop. State that changing slug: alone stays a configured default agent.

Low

• [logic-error] docs/glossary.md:75 — Always-on Skill has a Planned callout (Dynamically inject harness-listed skills into agent prompt frontmatter for always-on activation #6681/feat(#6681): inject harness skills into agent frontmatter for always-on activation #6859) but the body asserts present-tense shipped behavior: harness skills: are injected into agent-definition skills: frontmatter at bootstrap. On-demand Skill correctly describes today's upload-and-list path and calls frontmatter injection the long-term mechanism, contradicting Always-on Skill's tense.
  Remediation: Rewrite the Always-on Skill body in future/conditional tense ("will be injected once Dynamically inject harness-listed skills into agent prompt frontmatter for always-on activation #6681 lands") and note that today's harness-listed skills follow the upload-and-list path under On-demand Skill.

• [internal-inconsistency] docs/glossary.md:268 — Repo Skill (and Skill Override / the default-vs-custom.md .agents/skills/ row this PR edited) says Claude Code's personal-over-project precedence "silently ignores" a same-named repo skill. warnRepoSkillCollisions in internal/cli/skill_collision.go, invoked from internal/cli/run.go when the runtime is Claude Code, logs a StepWarn for exactly this collision. "No bootstrap error" is accurate; "silently" overstates operator-visible behavior.
  Remediation: Say there is no bootstrap error / fail-fast, and note that Fullsend emits a warning on the Claude Code runtime when a repo skill basename collides with a harness-listed skill.

• [consumer-completeness] docs/glossary.md:268 — Repo Skill names Claude Code (discovers .agents/skills) and runtime: pi (does not). It omits Codex, which docs/contributing/runtime-implementation.md and docs/runtimes/codex.md document as discovering a repo's .agents/skills with the project untrusted (Claude Code parity).
  Remediation: Mention Codex alongside Claude Code as discovering repo .agents/skills (project-untrusted parity), keeping the runtime: pi non-discovery caveat.

• [naming-convention] docs/glossary.md:289 — The new Script Override entry uses Details: as its reference-line prefix instead of the established See prefix used by every other glossary entry with a reference line.
  Remediation: Move the reference list to its own line starting with See immediately following the definition text.

• [code-organization] docs/glossary.md:287 — The new ### Script Override entry is placed after ### Sidecar under the ## S section, breaking alphabetical ordering ("Sc" should precede "Si").
  Remediation: Move ### Script Override before ### Sidecar to preserve alphabetical ordering under ## S.

• [code-organization] docs/glossary.md:236 — The new ### On-demand Skill entry is placed after ### OTEL Primary Facts under the ## O section, breaking alphabetical ordering ("On" should precede "OT").
  Remediation: Move ### On-demand Skill before ### OTEL Derived Products (immediately after ### Observability) to preserve alphabetical ordering under ## O.

• [incorrect-doc] docs/agents/triage.md:100 — docs/agents/triage.md and docs/agents/review.md (line ~70) still instruct users to override the built-in issue-labels skill by creating .agents/skills/issue-labels/SKILL.md and symlinking .claude/skills to it. That path is shadowed under the Claude Code runtime's personal-over-project precedence, which this PR now makes canonical vocabulary via the new Repo Skill / Skill Override glossary entries. Pre-existing contradiction (not introduced by this PR, and docs/guides/user/customizing-with-skills.md already documents the shadowing/warning/base: override path), but surfaced by this PR's new authoritative terminology.
  Remediation: In a follow-up, update docs/agents/triage.md and docs/agents/review.md to drop the .agents/skills/issue-labels drop-in as an "override" path and point at base: harness composition per docs/guides/user/customizing-with-skills.md#overriding-built-in-skills.

• [stale-doc] docs/agents/topics/escalation-ladder.md:111 — The Level 3 example still uses a base: URL under fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/code.yaml, and lines 80-83 still say harness/scripts/skills/agent-definitions may live in fullsend-ai/fullsend. This PR fixes the identical stale fullsend-ai/fullsend → fullsend-ai/agents harness-lineage reference in the sibling file docs/agents/topics/default-vs-custom.md, leaving escalation-ladder.md as the one remaining example of the same pattern. Pre-existing issue, not introduced by this PR.
  Remediation: Update the Level 3 example URL to point at fullsend-ai/agents/<sha>/harness/code.yaml and tighten the L80-83 parenthetical to attribute default harnesses/scripts/skills/agent definitions to fullsend-ai/agents.

---

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

Previous run (2)

Review

Findings

Critical

• [ADR numbering collision] docs/ADRs/0092-always-on-harness-skills.md:1 — ADR 0092 already exists on main as docs/ADRs/0092-openai-wif-credential-delivery.md. This PR creates a second file with the same number. Nineteen files across the codebase (workflow files, architecture.md, pi.md, Go source) reference ADR 0092 pointing to the OpenAI WIF ADR. Every cross-reference this PR adds to ADR 0092 (in glossary.md, architecture.md, codebase-context.md, ADR 0024, and customizing-with-skills.md) links to 0092-always-on-harness-skills.md, which would coexist with the other file. The base branch was likely created before ADR 0092 was merged on main.
  Remediation: Renumber the new ADR to 0093 (or the next available number after checking the highest ADR on main). Update all references in this PR's changed files.

Low

• [stale-reference] docs/agents/topics/escalation-ladder.md:111 — Example base: URL references fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/code.yaml. The scaffold harness directory has been extracted to fullsend-ai/agents (ADR 0058). This PR updates the sibling file default-vs-custom.md to reference fullsend-ai/agents, making this example inconsistent. Pre-existing issue not introduced by this PR.
  Remediation: Update the example URL to use fullsend-ai/agents/<sha>/harness/code.yaml.

• [naming-convention] docs/glossary.md:287 — Script Override uses Details: as its reference-line prefix instead of the established See prefix used by every other glossary entry with a reference line.
  Remediation: Change Details: to See for consistency.

---

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

Previous run (3)

Review

Findings

Low

• [broken-forward-reference] docs/glossary.md — Four references to ADRs/0092-always-on-harness-skills.md are added, but ADR 0092 does not exist on the main branch. The PR is stacked on PR docs(adr): add ADR 0092 always-on harness skills #6378 (base branch: docs/adr-0091-always-on-skills), which should introduce that ADR. If docs(adr): add ADR 0092 always-on harness skills #6378 does not merge first, these links will be broken. The ADR numbering is correct (ADR 0091 on main is "per-agent-runtime-model-effort").

• [code-organization] docs/glossary.md:7 — The new ## Customization vocabulary heading uses the same ## level as single-letter alphabetical groupings (## A, ## B, etc.). The --- separator provides a visual boundary, so this is cosmetic. A bold paragraph header would keep ## reserved for the alphabetical index.

• [naming-convention] docs/glossary.md:284 — Script Override uses Details: as its reference-line prefix instead of the established See prefix used by every other glossary entry with a reference line.

• [naming-convention] docs/glossary.md — Three new entries (AGENTS.md, Customized Agent, On-demand Skill) omit the trailing See [...] reference line that the majority of glossary entries use. Pre-existing entries (Evergreen, Rework Rate) also omit it, so this is not a strict rule.

---

Labels: PR modifies glossary and agent classification documentation under docs/

Previous run (4)

Review

Findings

Low

• [stale-reference] docs/agents/topics/escalation-ladder.md:80 — Lines 80–81 parenthetically list "(harness, scripts, skills, agent definitions)" under fullsend-ai/fullsend, but harness files and agent definitions now live in fullsend-ai/agents. Pre-existing issue not introduced by this PR; made more visible by glossary updates.

• [stale-reference] docs/agents/topics/escalation-ladder.md:111 — The base: URL example points to fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/code.yaml. Other user-facing docs already use fullsend-ai/agents/<sha>/harness/code.yaml. Pre-existing issue not introduced by this PR.

• [broken-forward-reference] docs/glossary.md — Four references to ADRs/0091-always-on-harness-skills.md are added, but ADR 0091 does not exist on the main branch. The PR is stacked on PR docs(adr): add ADR 0092 always-on harness skills #6378 (base branch: docs/adr-0091-always-on-skills), which structurally enforces merge ordering. Verify docs(adr): add ADR 0092 always-on harness skills #6378 merges first.

• [code-organization] docs/glossary.md:7 — The new ## Customization vocabulary heading uses the same ## level as single-letter alphabetical groupings (## A, ## B, etc.). The --- separator provides a visual boundary, so this is cosmetic. A bold paragraph header would keep ## reserved for the alphabetical index.

• [naming-convention] docs/glossary.md — Three new entries (AGENTS.md, Customized Agent, On-demand Skill) omit the trailing See [...] reference line that the majority of glossary entries use. Script Override uses inline references instead of a separate See line.

---

Labels: PR modifies glossary and agent classification documentation under docs/

Previous run (5)

Review

Findings

Medium

• [internal-consistency] docs/glossary.md — The Repo Skill entry states: "bootstrap uploads skills into one sandbox skills directory and fails fast on duplicate basenames." The Skill Override entry repeats this: "Do not rely on a same-named repo skill; duplicate basenames fail fast at bootstrap." However, docs/guides/user/customizing-with-skills.md (lines 88–91 and 105–107) states the opposite behavior: repo skills with matching names are "silently ignored" / "shadowed — the agent never sees it." These are contradictory behavioral claims about what happens when a repo skill name collides with a built-in skill. Determine the actual runtime behavior and align both documents.

• [stale-reference] docs/agents/topics/escalation-ladder.md:80 — Lines 80–83 parenthetically list "(harness, scripts, skills, agent definitions)" under fullsend-ai/fullsend, but this PR's glossary updates assert that harness files and agent definitions now live in fullsend-ai/agents. The existing text already mentions both repos, but the parenthetical on the fullsend line is now inaccurate. Pre-existing issue made more visible by this PR.

• [stale-reference] docs/agents/topics/escalation-ladder.md:111 — The base: URL example points to fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/code.yaml. Other user-facing docs (bring-your-own-agent.md, code.md, fix.md) already use the new path fullsend-ai/agents/<sha>/harness/code.yaml. Pre-existing issue; consider updating opportunistically.

Low

• [broken-forward-reference] docs/glossary.md — Four references to ADRs/0091-always-on-harness-skills.md are added, but ADR 0091 does not exist on the main branch. The PR is stacked on PR docs(adr): add ADR 0092 always-on harness skills #6378 (base branch: docs/adr-0091-always-on-skills), which structurally enforces merge ordering. Verify docs(adr): add ADR 0092 always-on harness skills #6378 merges first.

• [code-organization] docs/glossary.md:7 — The new ## Customization vocabulary heading uses the same ## level as single-letter alphabetical groupings (## A, ## B, etc.). The --- separator provides a visual boundary, so this is cosmetic. Consider a bold paragraph header to keep ## reserved for alphabetical sections.

• [naming-convention] docs/glossary.md — Three entries (On-demand Skill, AGENTS.md, Customized Agent) omit the trailing See [...] reference line that most glossary entries use. Script Override uses Details: instead of See. The convention is not universal (Evergreen and Rework Rate also omit it), but consistency would improve.

Previous run (6)

Review

Findings

Medium

• [internal-consistency] docs/glossary.md — The Repo Skill entry states: "bootstrap uploads skills into one sandbox skills directory and fails fast on duplicate basenames." The Skill Override entry repeats this: "Do not rely on a same-named repo skill; duplicate basenames fail fast at bootstrap." However, docs/guides/user/customizing-with-skills.md (lines 88–91 and 105–107) states the opposite behavior: repo skills with matching names are "silently ignored" / "shadowed — the agent never sees it." These are contradictory behavioral claims about what happens when a repo skill name collides with a built-in skill. Align the glossary with the guide (or vice versa) — if the runtime silently shadows, change the glossary entries; if "fail fast" is the intended new behavior (e.g., from ADR 0091), update the guide.

Low

• [code-organization] docs/glossary.md:7 — The new ## Customization vocabulary heading uses the same ## level reserved for single-letter alphabetical groupings (## A, ## B, etc.) throughout the rest of the glossary. The section sits above the --- separator, which provides a natural visual boundary, so this is cosmetic rather than structural. Consider demoting to a bold paragraph header or callout block to keep ## exclusively for alphabetical sections.

• [naming-convention] docs/glossary.md — The ### On-demand Skill, ### AGENTS.md, ### Customized Agent, and ### Script Override entries omit the trailing See [...] reference line that most other glossary entries use. Adding standalone See lines would improve consistency with the established pattern (though the convention is not universal — existing entries like Evergreen and Rework Rate also omit it).

• [broken-forward-reference] docs/glossary.md — Four references to ADRs/0091-always-on-harness-skills.md are added, but ADR 0091 does not exist on the main branch. The PR is stacked on PR docs(adr): add ADR 0092 always-on harness skills #6378 (base branch: docs/adr-0091-always-on-skills), which structurally enforces merge ordering and reduces the risk of broken links. Verify docs(adr): add ADR 0092 always-on harness skills #6378 merges first.

• [stale-reference] docs/agents/topics/escalation-ladder.md:111 — The Level 3 example URL still points to fullsend-ai/fullsend for a harness file. This PR updates the glossary and default-vs-custom.md to assert that harness files live in fullsend-ai/agents, making the escalation-ladder example inconsistent. This is a pre-existing issue made more visible by this PR.

---

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

Previous run (7)

Review

Findings

Low

• [code-organization] docs/glossary.md:7 — The new ## Customization vocabulary heading uses the same ## level reserved for single-letter alphabetical groupings (## A, ## B, etc.) throughout the rest of the glossary. The section is deliberately placed above the --- separator in the preamble area, which provides a natural visual boundary, so this is cosmetic rather than structural. Consider demoting to a bold paragraph header or callout block to keep ## reserved for alphabetical sections.

• [scope-authorization-indirect] docs/glossary.md — No issue is directly linked to this PR. Authorization is inferred indirectly through the dependency chain: PR docs(adr): add ADR 0092 always-on harness skills #6378 (which fixes issue Harness-listed team skills do not reliably apply without default-prompt naming #6380) → this PR (glossary vocabulary for the same feature area). Consider adding a reference to Harness-listed team skills do not reliably apply without default-prompt naming #6380 in the PR body for explicit traceability.

Info

• [provenance-warning] — Prior review context discarded: provenance validation failed (unverifiable-wrong-app). This review treats all findings as first-time assessments.

Previous run (8)

Review

Findings

Low

• [edge-case-correctness] docs/glossary.md:107 — The Configured Default Agent entry lists "skill overrides that do not replace identity fields" as an allowed path. The qualifier "that do not replace identity fields" is technically redundant — skill overrides by definition replace skills, not identity fields (agent:, scripts, slug). The phrasing could imply skill overrides that DO replace identity fields exist, which would be contradictory. Consider simplifying to just "skill overrides."

• [internal-consistency] docs/glossary.md:249 — The Repo Skill entry explains shadowing via "built-ins are installed at a higher-precedence config layer than repo skills, so the built-in wins on collision." While accurate in outcome (built-in wins), the underlying mechanism is that repo skills don't participate in base composition's dedup-by-basename merge — not that they lose a precedence contest. For a glossary entry, the outcome-level description is adequate but could be more precise.

• [cross-reference] docs/glossary.md:249 — The Repo Skill entry uses bold on "not" (**not** a skill override). This negative-bold pattern is atypical for the glossary, where bold is reserved for status markers (**Removed.**) and field names rather than negation emphasis.

[ascerra]

/fs-fix

[qodo-code-review]

PR Summary by Qodo

docs(glossary): add customization vocabulary for agents, skills, and scripts

📝 Documentation ✨ Enhancement 🕐 20-40 Minutes

AI Description

• Add a “Customization vocabulary” index to disambiguate “customized agent” discussions.
• Define precise terms for agent identity (default/configured/derived/custom) and modification
 types.
• Document skill load modes (always-on vs on-demand) and clarify skill/script override semantics.

Diagram

graph TD
  G["docs/glossary.md"] --> CV(["Customization vocab"])
  CV --> AI(["Agent identity"])
  AI --> DVC["Default vs custom doc"]
  CV --> SK(["Skills terms"])
  SK --> CS["Skills guide"] --> ADR91[("ADR 0091")]
  CV --> SC(["Scripts terms"])
  SC --> ADR24[("ADR 0024")] --> ADR17[("ADR 0017")]
  CV --> BY(["BYOA concept"])
  BY --> BYDOC["BYOA guide"] --> ADR58[("ADR 0058")]

  subgraph Legend
    direction LR
    _c([Concept]) ~~~ _d["Doc"] ~~~ _a[(ADR)]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Dedicated “Customization taxonomy” doc (non-glossary)

• ➕ Allows longer narrative explanations and examples without bloating the glossary
• ➕ Can evolve into a single canonical page referenced by other docs
• ➖ Adds another entry point; readers may still need quick glossary definitions
• ➖ Requires maintaining two places (taxonomy doc + glossary anchors) unless glossary becomes a stub

2. Put taxonomy into default-vs-custom page and keep glossary minimal

• ➕ Keeps definitions close to the primary conceptual guide
• ➕ Reduces cross-link surface area inside the glossary
• ➖ Harder to discover for readers who start at the glossary for terminology
• ➖ Glossary loses its role as the shared vocabulary index

3. Use a formal ADR for terminology decisions

• ➕ Clear decision record and rationale for naming and boundaries
• ➕ Easier to reference as “project decision” in debates
• ➖ Heavier-weight process for vocabulary changes
• ➖ Still need glossary entries for quick lookup

Recommendation: Current approach (glossary-first taxonomy index + anchored terms + links to canonical guides/ADRs) is the best default because it optimizes for discoverability and shared language in discussions. If the glossary grows too large, consider extracting the index narrative into a dedicated taxonomy page while keeping the glossary definitions and anchors as the stable reference surface.

Files changed (1) +111 / -14

Documentation (1) +111 / -14

glossary.mdAdd customization vocabulary index and new agent/skill/script terms +111/-14

Add customization vocabulary index and new agent/skill/script terms

• Introduces a new “Customization vocabulary” section that classifies agent identity (default/configured/derived/custom) and distinguishes additive vs override skills plus script overrides. Adds new glossary entries (e.g., Additive Skill, Built-in Skill, Repo Skill, Always-on/On-demand Skill, Extension Point, BYOA, Pre/Post-script) and refines existing definitions to align with base composition and ADR references (notably ADR 0091). Repositions the Slash Command entry within the glossary ordering.

docs/glossary.md

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 6:56 PM UTC · Completed 7:01 PM UTC

Commit: c6ab34e · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 6:56 PM UTC · Ended 7:02 PM UTC

Commit: c6ab34e · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed all 3 low-severity review findings: removed a redundant qualifier in Configured Default Agent, corrected the mechanism description in Repo Skill from precedence-based to layer-isolation-based, and removed atypical bold emphasis in Repo Skill.

Fixed (3):

1. Redundant qualifier in Configured Default Agent entry: Removed 'that do not replace identity fields' from the skill overrides mention in Configured Default Agent. Skill overrides by definition replace skills by basename, not identity fields (agent:, scripts, slug), so the qualifier was redundant and could imply a nonexistent variant.
2. Imprecise mechanism description in Repo Skill entry: Replaced 'built-ins are installed at a higher-precedence config layer than repo skills' with 'repo skills do not participate in base composition's dedup-by-basename merge'. This accurately describes the layer isolation mechanism rather than implying a precedence contest.
3. Atypical bold on 'not' in Repo Skill entry: Removed bold from 'not' (not → not) in 'That silent shadowing is not a skill override' to match the glossary convention where bold is reserved for status markers and field names.

Tests: passed

Next steps:

• /fs-review — request a re-review of the changes
• /fs-fix <your instruction> — run another fix pass with specific guidance
• Push commits directly — review re-runs automatically on push
  _{Updated by fullsend fix agent}

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Repo skill collision misdescribed ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new “Repo Skill” entry says a repo skill that matches a built-in skill name is silently shadowed
(built-in wins), but the runtime uploads all skills into the same sandbox skills directory and fails
fast on duplicate basenames. This documentation mismatch will lead users to create colliding skills
expecting an override, but runs will error during bootstrap instead.

Code

docs/glossary.md[R249-250]

+A [skill](#skill) committed under the target repo (typically `.agents/skills/`, often symlinked as `.claude/skills`). Discovered for agents on that repo. Novel names are [additive](#additive-skill). A repo skill whose **name matches** a [built-in skill](#built-in-skill) is shadowed — built-ins are installed at a higher-precedence config layer than repo skills, so the built-in wins on collision. That silent shadowing is **not** a [skill override](#skill-override); use [base composition](#base-composition) (same basename on the child harness `skills:` list) or see that entry.
+See [Configuring with skills](guides/user/customizing-with-skills.md).

Relevance

●●● Strong

Recent reviews accepted corrections where documentation contradicted runtime behavior; this is a
concrete collision-semantics mismatch.

PR-#5945
PR-#6335

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The glossary claims silent shadowing on name collision, but the runtime creates one shared
configDir/skills directory, checks input.SkillDirs() for duplicate destination basenames, and
returns an error when two distinct skill paths share the same basename (so collisions fail rather
than being resolved in favor of built-ins).

docs/glossary.md[247-250]
internal/runtime/claude.go[43-71]
internal/runtime/claude.go[249-274]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`docs/glossary.md` states that a repo skill whose name matches a built-in skill is "shadowed" (built-in wins). In the implementation, skills are uploaded into a single `CLAUDE_CONFIG_DIR/skills` directory and duplicate destination basenames cause bootstrap to return an error.

### Issue Context
This glossary is intended to be precise vocabulary; this specific claim currently contradicts the runtime’s collision handling and will mislead readers into creating configurations that fail at runtime.

### Fix Focus Areas
- docs/glossary.md[247-250]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Unimplemented bootstrap paste noted ✓ Resolved 📜 Skill insight ≡ Correctness

Description

The glossary documents an unimplemented behavior (bootstrap paste path) without using the required
> **Planned:** callout format and without linking to a tracking issue. This can mislead readers
into treating planned functionality as current behavior and violates the documentation convention
for planned features.

Code

docs/glossary.md[74]

+A harness [skill](#skill) load mode decided in [ADR 0091](ADRs/0091-always-on-harness-skills.md): frontmatter `apply: always` means bootstrap pastes the `SKILL.md` body into the copied agent definition for that run so the model always sees it (no Skill-tool open required). Adding such a skill via `skills:` on a thin `base:` wrapper keeps a [configured default](#configured-default-agent); replacing `agent:` just to name the skill would make it [derived](#derived-agent). Contrast with [on-demand skill](#on-demand-skill). Until bootstrap implements the paste path, treat this as the decided contract rather than a guarantee of every running install.

Relevance

●●● Strong

Recent docs review accepted labeling unimplemented behavior as Planned; this finding matches an
explicit repository convention.

PR-#6398

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062082 requires any mention of not-yet-implemented features to use a `>
**Planned:**` blockquote callout and include an issue link. The added glossary entry explicitly
states the behavior is not yet implemented (“Until bootstrap implements the paste path...”) but does
not use the required callout format nor provide an issue link.

docs/glossary.md[72-74]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/glossary.md` mentions not-yet-implemented behavior (“Until bootstrap implements the paste path...”) but does not use the required `> **Planned:**` blockquote callout format and does not include a link to a tracking issue.

## Issue Context
Compliance requires that planned/unimplemented features be clearly marked using the `> **Planned:**` callout and include a link to the relevant issue so readers can verify status and track delivery.

## Fix Focus Areas
- docs/glossary.md[72-74]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 58 rules

✅ Skills: writing-user-docs, writing-adrs

Tip of the day

💡 Did you know, you can turn these tips off under Display preferences

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:03 PM UTC · Completed 7:19 PM UTC

Commit: cc965f3 · View workflow run →

[waynesun09]

Review findings from an automated pass (3 inline comments on docs/glossary.md plus one below on a linked doc that isn't part of this PR's diff).

[MEDIUM] AGENTS.md glossary entry funnels readers to a citation that misattributes the open standard
File: docs/guides/user/customizing-with-agents-md.md (line 13) — not touched by this PR's diff, so noted here rather than as an inline comment.

This PR adds a new, prominent AGENTS.md glossary entry (docs/glossary.md lines 68-70) that links to docs/guides/user/customizing-with-agents-md.md, which states "AGENTS.md is the open standard (https://agentskills.io/) that any agent tool can discover." Checking both sites: agentskills.io is entirely about the unrelated Agent Skills / SKILL.md format ("a lightweight, open format for extending AI agent capabilities... originally developed by Anthropic"), not AGENTS.md files. The actual AGENTS.md standard is at https://agents.md/ ("A simple, open format for guiding coding agents," now stewarded by the Agentic AI Foundation under the Linux Foundation). The linked guide conflates two unrelated open formats, and this PR's new glossary term makes that wrong citation more visible/consequential by pointing readers straight at it.

Suggestion: fix the citation in docs/guides/user/customizing-with-agents-md.md to point to https://agents.md/, keeping agentskills.io only where the topic is genuinely Agent Skills (as already done correctly in docs/guides/user/customizing-with-skills.md). Consider doing this in the same PR or a fast-follow since this PR is specifically the vocabulary/reference-hygiene pass touching this exact term.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:50 AM UTC · Completed 12:08 PM UTC

Commit: 8fd7bb0 · View workflow run →

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

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 3:38 PM UTC · Ended 3:55 PM UTC

Commit: 5416809 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Superseded by updated review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:38 PM UTC · Completed 3:55 PM UTC

Commit: 5416809 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $4.05

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:32 PM UTC · Completed 5:49 PM UTC

Commit: a11bc35 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $4.09

Superseded by updated review

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 11:37 AM UTC · Completed 11:53 AM UTC

Commit: a11bc35 · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.52

[fullsend-ai-retro]

PR #6383 was a human-authored docs PR (glossary/customization vocabulary), not an agent triage→code pipeline, so this retro focuses on review quality and autonomy readiness across ~22 days, 9 push/review/fix round-trips, 8 fullsend-ai-review passes, and 1 qodo-code-review pass. The automated review agent's own findings were almost entirely cosmetic (heading levels, alphabetization, wording nits) plus one genuinely valuable catch (an ADR-0092 numbering collision). Nearly every substantive issue — a stale harness-lineage claim, terminology self-contradictions, hardcoded skill names violating AGENTS.md conventions, a factually wrong behavioral claim, and (most importantly) that the entire ADR/design section being shipped had been reversed by decisions made in other issues/PRs — was caught only by human reviewer waynesun09 via deep source and cross-reference verification. One human-flagged issue was never fixed and remains live on main today: docs/guides/user/customizing-with-agents-md.md:13 cites https://agentskills.io/ (the unrelated Agent Skills/SKILL.md spec) as the AGENTS.md standard instead of https://agents.md/; this was raised 2026-08-21 as an out-of-diff comment and silently dropped. I filed one new proposal to close that out. For the underlying systemic gaps, I found this PR provides strong corroborating evidence for several already-open issues rather than filing duplicates: #1656 (fullsend/fullsend) — review agent should verify external claims/citations against outside sources: this PR's agentskills.io error survived all 8 review passes with no such check. #2199 (fullsend/fullsend) — review agent should fact-check technical claims against the codebase: a qodo-sourced claim that repo-skill collisions "fail fast" (actually they silently shadow, per internal/runtime/claude.go) was applied to the docs and went uncaught by fullsend-ai-review for 4 days until a human verified it. #3695 / #1352 (fullsend/fullsend) — out-of-diff findings get raised but never tracked as follow-ups: two pre-existing issues (docs/agents/topics/escalation-ladder.md stale base: URL; stale skill-override instructions in docs/agents/triage.md/review.md) were re-flagged near-identically across 5+ review passes over 3 weeks and never converted into a tracked issue — the same failure mode that lost the agentskills.io finding. #1568 (fullsend/fullsend) and #726 (fullsend/agents) — detecting stale/superseded cross-references: the docs-review skill only checks doc-vs-code staleness, not doc-vs-linked-issue/PR staleness, which is exactly what would have caught the reversed-ADR-design problem here; #1568 is currently scoped narrowly to ADR-to-ADR references, so I'd suggest whoever picks it up consider generalizing it to doc-to-issue/PR references (per #726's fetch-and-compare mechanism) using #6383 as a second data point. No proposal filed for qodo-code-review's incorrect finding specifically, since the actionable fix (independent verification of behavioral claims regardless of source) is already the subject of #2199.

Proposals filed

• Fix incorrect AGENTS.md standard citation in customizing-with-agents-md.md (links to agentskills.io instead of agents.md) (in fullsend-ai/fullsend)