Skip to content

chore(docs): pull agent documentation from fullsend-ai/agents - #6953

Closed
rh-hemartin wants to merge 1 commit into
mainfrom
feat/inject-agents
Closed

rh-hemartin wants to merge 1 commit into
mainfrom
feat/inject-agents

Conversation

@rh-hemartin

@rh-hemartin rh-hemartin commented Sep 3, 2026 •

Copy link
Copy Markdown
Member

Summary

Add fullsend-ai/agents as a git submodule and serve its docs/ folder from docs/agents on the documentation site, so agent pages stay in sync with the agents repo instead of being copied by hand.

Related Issue

Closes #5710

Changes

  • Add the agents submodule at the repo root and replace docs/agents with a symlink to agents/docs
  • Auto-discover agent pages in the VitePress sidebar via getMarkdownFiles
  • Move default-vs-custom and escalation-ladder pages into docs/guides/user/
  • Rebuild the docs site when agents/ changes, matching the existing experiments/ path filters
  • Due to pulling the agent docs from the original repository, the sidebar now orders the pages alphabetically. That is OK for now, we may change it in the future to be more sophisticated.

Testing

  • make lint passes (stage changes first, then run)
  • Tests added/updated for new or modified logic

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO) — human and human-directed agent sessions only
  • I wrote this contribution myself and can explain all changes in it

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Started 10:19 AM UTC · Ended 10:40 AM UTC

Commit: f7c716f · View workflow run →

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Source agent docs from the fullsend-ai/agents submodule

✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Grey Divider

AI Description

• Sources agent reference pages from a pinned fullsend-ai/agents submodule through docs/agents.
• Auto-discovers agent sidebar entries and keeps customization guides in local user documentation.
• Rebuilds documentation whenever the agents submodule or its contents change.
Diagram

graph TD
  A["Agents Repository"] -->|pinned commit| B["Agents Submodule"] -->|docs source| C["Docs Symlink"] -->|markdown| D["VitePress Build"] --> E["Docs Site"]
  F["VitePress Config"] -->|discovers pages| D
  G["Site Workflow"] -->|runs on changes| D
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Build-time repository checkout
  • ➕ Avoids a permanent git submodule and symlink in contributor checkouts.
  • ➕ Can select a branch or tag independently during the documentation build.
  • ➖ Requires additional CI authentication and checkout logic.
  • ➖ Following a branch would make builds non-reproducible unless the commit is explicitly pinned.
  • ➖ Local documentation builds would need equivalent bootstrap tooling.
2. Git subtree import
  • ➕ Produces ordinary files that work without submodule initialization or symlink support.
  • ➕ Keeps local and CI documentation builds self-contained.
  • ➖ Reintroduces imported copies into the main repository.
  • ➖ Subtree updates create large synchronization commits and obscure upstream ownership.
  • ➖ Automated sidebar discovery would still be required.

Recommendation: The pinned submodule and symlink are the best fit because they preserve upstream ownership while keeping site builds reproducible. Explicit submodule updates are preferable to following the upstream branch implicitly; the existing build already initializes submodules, limiting additional CI complexity.

Files changed (7) +19 / -14

Enhancement (1) +6 / -10
config.tsDiscover agent pages and relocate customization navigation +6/-10

Discover agent pages and relocate customization navigation

• Replaces the hardcoded agent page list with getMarkdownFiles-based discovery from docs/agents. Adds the default-versus-custom and escalation-ladder guides under the Customizing Agents sidebar group.

docs/.vitepress/config.ts

Documentation (2) +4 / -4
default-vs-custom-agents.mdMove agent classification guidance into user guides +0/-0

Move agent classification guidance into user guides

• Relocates the default, derived, and custom agent classification page from the agent reference area into the local user-guide hierarchy.

docs/guides/user/default-vs-custom-agents.md

escalation-ladder.mdMove escalation guidance and repair sibling links +4/-4

Move escalation guidance and repair sibling links

• Relocates the agent customization escalation ladder into user guides. Updates references to target the renamed default-vs-custom-agents page in the same directory.

docs/guides/user/escalation-ladder.md

Other (4) +9 / -0
site-build.ymlRebuild the site for agents submodule changes +4/-0

Rebuild the site for agents submodule changes

• Adds the agents gitlink and descendant paths to pull-request and main-branch path filters. Documentation builds now run when the pinned agent documentation source changes.

.github/workflows/site-build.yml

.gitmodulesRegister the fullsend-ai/agents submodule +3/-0

Register the fullsend-ai/agents submodule

• Defines the root-level agents submodule using the fullsend-ai/agents GitHub repository as its source.

.gitmodules

agentsPin the agents documentation repository +1/-0

Pin the agents documentation repository

• Adds the agents gitlink pinned to commit 81b0e9bde0fae533bb4e26a731c0bca343340d79.

agents

agentsLink VitePress to upstream agent documentation +1/-0

Link VitePress to upstream agent documentation

• Replaces the locally maintained agent documentation directory with a symlink to the agents submodule's docs directory.

docs/agents

@qodo-code-review

qodo-code-review Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

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

Grey Divider


Action required

1. Moved pages break inbound links ✓ Resolved 🐞 Bug ≡ Correctness
Description
Seventeen existing documentation links still target /agents/topics/default-vs-custom or
/agents/topics/escalation-ladder, but replacing docs/agents with the submodule symlink removes
those pages while their replacements are published under /guides/user/. These links now lead to
nonexistent pages.
Code

docs/agents[1]

+../agents/docs/
Relevance

●●● Strong

Broken internal documentation links are accepted correctness findings when destinations move or
filenames change.

PR-#601
PR-#226

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The symlink replaces the former local agents tree, and the sidebar publishes the moved pages under
/guides/user/. The cited files retain links to the old /agents/topics/ paths, so their
destinations no longer exist.

docs/agents[1-1]
docs/.vitepress/config.ts[270-274]
docs/cli/agent.md[121-121]
docs/glossary.md[48-75]
docs/guides/README.md[57-57]
docs/guides/user/adoption.md[94-94]
docs/guides/user/bring-your-own-agent.md[381-382]
docs/guides/user/building-custom-agents.md[12-14]
docs/guides/user/customizing-agents.md[398-399]
docs/guides/user/customizing-overview.md[129-130]
docs/guides/user/customizing-with-agents-md.md[153-153]
docs/guides/user/customizing-with-skills.md[197-197]

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

## Issue description
Update every internal link that still targets the removed `agents/topics/default-vs-custom.md` or `agents/topics/escalation-ladder.md` routes so it points to the corresponding page under `guides/user/`.

## Issue Context
`docs/agents` is now backed by the agents submodule, while these two pages were moved into `docs/guides/user/`. Existing inbound links were not migrated.

## Fix Focus Areas
- docs/cli/agent.md[121-121]
- docs/glossary.md[48-75]
- docs/guides/README.md[57-57]
- docs/guides/user/adoption.md[94-94]
- docs/guides/user/bring-your-own-agent.md[381-382]
- docs/guides/user/building-custom-agents.md[12-14]
- docs/guides/user/customizing-agents.md[398-399]
- docs/guides/user/customizing-overview.md[129-130]
- docs/guides/user/customizing-with-agents-md.md[153-153]
- docs/guides/user/customizing-with-skills.md[197-197]

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


2. New guides missing index entries ✓ Resolved 📜 Skill insight ⚙ Maintainability
Description
The PR adds sidebar entries for default-vs-custom-agents.md and escalation-ladder.md under
docs/guides/user/ without updating docs/guides/README.md. The guide index still links to the
removed docs/agents/topics/default-vs-custom.md location and contains no escalation-ladder entry.
Code

docs/.vitepress/config.ts[R270-274]

+                {
+                  text: "Default, derived and custom agents",
+                  link: "/guides/user/default-vs-custom-agents.md",
+                },
+                { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" },
Relevance

●●● Strong

Recent accepted precedents require new guides to appear in README indexes.

PR-#5778
PR-#2549

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 1062084 requires new guides to be included in docs/guides/README.md. The sidebar adds both
user-guide paths, while the index retains the former agents/topics path and does not list the
escalation guide.

docs/.vitepress/config.ts[270-274]
docs/guides/README.md[43-58]
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
Two guides were introduced under `docs/guides/user/`, but the guide index was not updated for their new locations.

## Issue Context
PR Compliance ID 1062084 requires `docs/guides/README.md` to be updated whenever a guide is added. Replace the stale topics link and add an entry for the escalation ladder.

## Fix Focus Areas
- docs/guides/README.md[43-58]
- docs/.vitepress/config.ts[270-274]

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


3. Moved guide links are broken ✓ Resolved 📜 Skill insight ≡ Correctness
Description
The guides retain relative links written for their former docs/agents/topics/ location, so links
such as ../../guides/user/... now resolve under nonexistent docs/guides/guides/user/, while the
two ../ links in default-vs-custom-agents.md resolve to the Guides index instead of the Agents
reference. Consequently, multiple customization and agent-reference links lead users to missing
pages or the wrong documentation section.
Code

docs/.vitepress/config.ts[R270-274]

+                {
+                  text: "Default, derived and custom agents",
+                  link: "/guides/user/default-vs-custom-agents.md",
+                },
+                { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" },
Relevance

●●● Strong

Broken relative documentation links are consistently accepted, including after guide moves.

PR-#601
PR-#226

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 1062085 requires every internal guide link to resolve, and the sidebar establishes the new
/guides/user/default-vs-custom-agents location. From docs/guides/user/, retained
../../guides/user/... links resolve into the nonexistent docs/guides/guides/user/ directory,
while ../ resolves to docs/guides/ even though the actual Agents reference is exposed at
docs/agents.

docs/.vitepress/config.ts[270-274]
docs/guides/user/default-vs-custom-agents.md[73-73]
docs/guides/user/escalation-ladder.md[43-50]
docs/.vitepress/config.ts[270-273]
docs/guides/user/default-vs-custom-agents.md[45-49]
docs/guides/user/default-vs-custom-agents.md[89-95]
docs/guides/README.md[1-5]
docs/agents[1-1]
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
Correct the relative links retained from the guides' former directory so that sibling user-guide links resolve within `docs/guides/user/` and agent-reference links resolve to `docs/agents/`, rather than to nonexistent paths or the Guides index.

## Issue Context
These guides moved from `docs/agents/topics/` to `docs/guides/user/`, but some links still use traversal calculated from the old location. From the new directory, `../../guides/user/...` resolves under nonexistent `docs/guides/guides/user/`, and `../` resolves to `docs/guides/` rather than the Agents reference at `docs/agents/`.

## Fix Focus Areas
- docs/guides/user/default-vs-custom-agents.md[45-53]
- docs/guides/user/default-vs-custom-agents.md[89-103]
- docs/guides/user/escalation-ladder.md[41-50]
- docs/guides/user/escalation-ladder.md[183-194]

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


View high (1)
4. Moved guides omit prerequisites 📜 Skill insight ✧ Quality
Description
The newly registered escalation-ladder.md guide immediately instructs readers to follow a
four-level procedure but has no clearly labeled prerequisites section. Readers are not told what
access, configuration, or knowledge they need before beginning Level 1.
Code

docs/.vitepress/config.ts[274]

+                { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" },
Relevance

●●● Strong

Recent guide reviews accepted adding clearly labeled prerequisites before procedural instructions.

PR-#2663
PR-#6455

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 1062078 requires a prerequisites section before procedural steps. The sidebar addition
registers the document as a user guide, while its opening proceeds directly from a status callout to
instructions to start at Level 1 without any prerequisites section.

docs/.vitepress/config.ts[270-274]
docs/guides/user/escalation-ladder.md[1-20]
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
The newly placed escalation-ladder guide contains a procedural escalation path without a clearly labeled prerequisites section.

## Issue Context
PR Compliance ID 1062078 requires every guide to state prerequisites before its procedure begins.

## Fix Focus Areas
- docs/guides/user/escalation-ladder.md[1-20]

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



Remediation recommended

5. escalation-ladder procedure is unnumbered ✓ Resolved 📜 Skill insight ✧ Quality
Description
The guide tells readers to start at Level 1 and move through four levels, but presents the sequence
as prose, a code block, and separate headings rather than an ordered list. This makes the newly
introduced guide path noncompliant with the required procedure format.
Code

docs/.vitepress/config.ts[274]

+                { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" },
Relevance

●●● Strong

Reviewers repeatedly accepted converting procedural prose and code blocks into ordered steps.

PR-#2277
PR-#2663

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 1062079 requires procedural guide content to use ordered lists. The registered guide describes
an ordered escalation path but renders its four levels in a fenced block and prose before continuing
with level headings.

docs/.vitepress/config.ts[274-274]
docs/guides/user/escalation-ladder.md[8-34]
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
The escalation procedure is expressed through narrative prose, a code block, and headings instead of numbered procedural steps.

## Issue Context
The guide explicitly directs readers to begin at Level 1 and move upward, so the four levels form an ordered procedure under PR Compliance ID 1062079.

## Fix Focus Areas
- docs/guides/user/escalation-ladder.md[8-40]

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


6. Per-org removal unmentioned 📘 Rule violation § Compliance
Description
The replacement of docs/agents deletes documentation that explicitly discusses deprecated per-org
installation mode, but the PR description does not mention that impact or ADR 0044. The checklist
requires even removals of per-org-mode content to be called out explicitly.
Code

docs/agents/triage.md[77]

-**Defaults:** At install time, fullsend populates this with your org (in org mode — **deprecated**, see [ADR 0044](../ADRs/0044-deprecate-per-org-installation-mode.md)) or your repo (in per-repo mode), plus `fullsend-ai/fullsend` as an upstream target.
Relevance

●● Moderate

Deprecation documentation is enforced, but no close precedent confirms requiring PR-description
disclosure for removals.

PR-#5462
PR-#2743

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Rule 2795055 applies to removals as well as extensions or refactors and requires the PR description
to mention deprecated per-org installation mode and ADR 0044. The deleted triage documentation
explicitly contained both an org-mode reference and an ADR 0044 link, while the supplied PR
description discusses only the submodule and documentation synchronization.

Rule 2795055: Flag and avoid changes to deprecated per-org installation mode content (ADR 0044)


Grey Divider

Context sources
✅ Compliance rules (platform): 65 rules
Review mode: ⚖️ Balanced

Grey Divider

Tip of the day
💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread docs/.vitepress/config.ts Resolved
Comment thread docs/.vitepress/config.ts Resolved
Comment thread docs/.vitepress/config.ts Resolved
Comment thread docs/.vitepress/config.ts Resolved
Comment thread docs/agents/triage.md Resolved
Comment thread docs/agents Resolved
@github-actions

github-actions Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://9a7dd251-site.fullsend-ai.workers.dev

Commit: 4b59000792d6f1d13fcc85641032c370c4ee9cae

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 10:41 AM UTC · Completed 11:02 AM UTC

Commit: 229fa6f · View workflow run →

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

@codecov

codecov Bot commented Sep 3, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Re-review anchoring preserves the prior score of 2: Tier 1 signals are structurally unchanged (43 files/1311 lines, large blast radius, 4 protected-path hits, CI workflow touched, no dependency changes, neutral docs-only test ratio, non-bot non-first-time author), Tier 2 churn/fix-commit signals reflect ordinary long-running file history rather than any PR-specific regression signal, and Tier 3 confirms the PR still fully satisfies all three acceptance criteria of linked issue #5710 with no risk labels or unresolved discussion.

Previous run

Risk Assessment: moderate (2/5)

Details

Re-review anchoring confirms the prior score of 2: Tier 1 signals are structurally unchanged (43 files/1315 lines, large blast radius, 4 protected-path hits, CI workflow touched, no dependency changes, neutral docs-only test ratio), and no Tier 2 or Tier 3 evidence surfaced a specific reason to deviate - churn/authorship remains typical docs-restructuring activity with zero reverts or hack sentiment, and the PR still fully satisfies issue #5710's three-step acceptance criteria with only a single advisory label and no unresolved discussion.

Previous run (2)

Risk Assessment: moderate (2/5)

Details

Re-review anchoring confirms the prior score of 2: Tier 1 composite is driven by large blast radius, 4 protected-path hits, and CI workflow touch, offset by no dependency changes, no security-sensitive paths, and a neutral (docs-only) test ratio; Tier 2 shows expected high-churn/multi-author docs and config-site history with zero reverts and zero hack/workaround sentiment; Tier 3 confirms the PR fully satisfies issue #5710's acceptance criteria with only a single advisory label and no unresolved discussion.

Previous run (3)

Risk Assessment: moderate (2/5)

Details

Re-review anchoring preserves the prior score of 2: Tier 1 signals remain structurally the same (large blast radius, 4 protected-path hits, CI workflow touched, no dependency changes, docs-only so zero test ratio treated as neutral, non-bot/non-first-time author), Tier 2 shows expected high-churn/multi-author docs and config-site file history but zero reverts or hack/workaround commit sentiment, and Tier 3 confirms the PR substantially satisfies issue #5710's acceptance steps with only an implementation-detail deviation and a single advisory risk/moderate label, no unresolved discussion.

Previous run (4)

Risk Assessment: moderate (2/5)

Details

Re-review anchoring preserves the prior score of 2: Tier 1 metadata is unchanged (large blast radius, protected-path count still elevated after re-verifying the agents/ -> _agents/ rename, CI workflow touched, no test files — all structurally inflated by the docs-only submodule swap rather than genuine production risk), Tier 2 shows typical multi-author docs/config churn with no reverts or hack/workaround signals tied to this change, and Tier 3 confirms the PR fully satisfies issue #5710's acceptance criteria with no risk labels.

Previous run (5)

Risk Assessment: moderate (2/5)

Details

Re-review anchoring preserved the prior score of 2: Tier 1 signals are unchanged (large blast radius, 4 protected paths, CI workflow touched, no test files), Tier 2 shows typical multi-author doc/config churn with no reversions, and Tier 3 confirms all acceptance criteria are satisfied with no risk labels — the elevated metadata signal scores are structurally inflated by submodule and docs-only changes rather than representing genuine production risk.

Previous run (6)

Risk Assessment: moderate (2/5)

Details

Moderate risk — Tier 1 signals are unchanged from prior assessment (large blast radius, protected CI paths, no test files), but this remains fundamentally a documentation/submodule integration PR with no production code changes, no security-sensitive files, clear acceptance criteria fully satisfied, and straightforward rollback.

Previous run (7)

Risk Assessment: moderate (2/5)

Details

Moderate risk — large file count (41) and protected path changes (CI workflows) elevate Tier 1 signals, but this is fundamentally a documentation/submodule integration PR with no production code changes, clear acceptance criteria fully addressed, no security-sensitive files touched, and straightforward rollback.

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

Review

Findings

Medium

  • [logic-error] Makefile:184 — The new lychee exclusion --exclude-path ^_agents/ will not skip the agents submodule. Confirmed at the current line: lychee --offline --no-progress --include-fragments --exclude-path node_modules --exclude-path experiments --exclude-path ^_agents/ --exclude-path docs/agents/ --exclude-path docs/archived-roadmaps/2026-07.md '**/*.md'. lychee's --exclude-path is a path/glob matcher — the working in-repo pattern is --exclude-path experiments, with no regex anchors. A leading ^ is a literal character, so the matcher looks for a path starting with ^_agents/ and never hits _agents/. --exclude-path docs/agents/ only covers the symlink walk, not the real tree: lint-md-links globs '**/*.md', which also discovers _agents/**/*.md once the submodule is initialized (which lint.yml's new git submodule update --init _agents step now does before make lint-all runs). This exact bug was present at the prior review's commit and remains unfixed in this revision.
    Remediation: Replace --exclude-path ^_agents/ with --exclude-path _agents, matching the existing --exclude-path experiments form. Keep --exclude-path docs/agents/ if the symlink path should also stay excluded separately.

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, CODEOWNERS, skills/author-fullsend-augmentations/SKILL.md — This PR modifies 4 protected governance/infrastructure files: adds a submodule-init step to the default CI job in lint.yml, adds _agents path triggers to site-build.yml, adds a blank-owner CODEOWNERS entry for _agents, and updates path references in the augmentations skill. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and its description explains the rationale (surfacing fullsend-ai/agents docs on the site, following the existing experiments submodule pattern) consistently across these files. Human approval is always required for protected-path changes regardless of context.

Low

  • [logic-error] docs/doc-site.md:51 — The sentence claims that local site builds and make lint may require a manual git submodule update --init, but this overstates what this same PR automates: package.json's docs:dev/docs:build already run git submodule update --init, and the Makefile's ensure-hooks target (a prerequisite of make lint/make lint-all, also changed in this PR) now runs git submodule update --init _agents automatically when _agents is present but uninitialized.
    Remediation: Drop the make lint half of the manual-init sentence (it's now automatic via ensure-hooks), or narrow the sentence to cover only direct vitepress/mvb invocations that bypass the npm scripts and the Makefile.

  • [secret-exposure] .github/workflows/lint.yml:17 — The test job's actions/checkout step (line 17) has no with: block, so it defaults to persist-credentials: true. The subsequent git submodule update --init _agents step (line 24) then runs with that persisted GITHUB_TOKEN against a submodule URL and gitlink SHA that both come from the PR-controlled .gitmodules/gitlink, on every pull_request/push/merge_group (no path filter). The job's permissions: contents: read is unchanged and the persisted credential is host-scoped to github.com, so this is hardening rather than a demonstrated exploit — the same pattern already exists unmodified in site-build.yml — but this PR extends it to the always-running default CI job.
    Remediation: Set persist-credentials: false on the actions/checkout step in the test job of lint.yml (the job never pushes), matching the posture used elsewhere in the repo for read-only jobs.

  • [policy-coherence] CONTRIBUTING.md:170 — The new "Where to file agents-related issues" section mirrors the immediately preceding "Where to file experiments-related issues" section almost verbatim (table structure, repo-split framing, closing sentence), but presents the agents-repo filing split as settled policy. The experiments section it copies from carries an explicit caveat — "Status: proposed, pending maintainer confirmation" with tracking issue Decide where to track issues for fullsend-ai/experiments work #588 — because it documents a de facto pattern rather than a maintainer-ratified rule. The new section makes an equivalent unratified claim with no equivalent caveat or tracking issue, and this governance content isn't requested by the linked issue (Include fullsend-ai/agents docs in the documentation site #5710), which is scoped to submodule wiring and sidebar generation.
    Remediation: Either add a maintainer-confirmation caveat (with a tracking issue, matching the experiments section) to the new agents filing-split section, or drop the section from this PR and let it be proposed/ratified separately.

  • [documentation-staleness] skills/filing-issues/SKILL.md:26 — CONTRIBUTING.md's new "Where to file agents-related issues" section defines a repository split (agent definitions/harness/skills/schemas inside fullsend-ai/agents vs. submodule-integration concerns in fullsend-ai/fullsend), but skills/filing-issues/SKILL.md (not touched by this PR) still only documents the experiments/fullsend split: Step 1 doesn't cover fullsend-ai/agents, and Step 2's duplicate-search guidance only mentions searching both repos for experiments-related topics.
    Remediation: If the CONTRIBUTING.md agents filing section is kept, update skills/filing-issues/SKILL.md to add the fullsend-ai/agents repository split (mirroring the experiments table) and extend Step 2's duplicate-search guidance to also search fullsend-ai/agents when the topic is agents-related.

  • [documentation-staleness] AGENTS.md:21 — AGENTS.md's "Experiments issues" bullet explains the experiments/fullsend filing split and points to the corresponding CONTRIBUTING.md section. This PR adds a parallel "Where to file agents-related issues" section to CONTRIBUTING.md but does not add a corresponding "Agents issues" bullet to AGENTS.md (not touched by this PR), so contributors and agents reading this file's topic guidance table won't discover the new policy.
    Remediation: Add an "Agents issues" entry in AGENTS.md parallel to "Experiments issues", pointing to the new CONTRIBUTING.md section.

  • [documentation-staleness] docs/guides/user/escalation-ladder.md:78 — In "Level 2: Contribute to the default agent," the how-to-contribute paragraph still says: if the change is in fullsend-ai/fullsend (harness, scripts, skills, agent definitions), contribute there; if the agent definition or harness lives in fullsend-ai/agents, contribute there instead. That first branch's examples (harness, scripts, agent definitions living in fullsend-ai/fullsend) are stale relative to the repository split this same PR establishes in CONTRIBUTING.md, where those live in fullsend-ai/agents (the _agents/ submodule).
    Remediation: Update the Level 2 contribute paragraph so default-agent definitions, harnesses, scripts, and built-in skills are described as belonging in fullsend-ai/agents, consistent with the new CONTRIBUTING.md table.

  • [documentation-staleness] docs/guides/user/escalation-ladder.md:109 — The Level 3 example still uses a base: URL pointing into fullsend-ai/fullsend's internal/scaffold/fullsend-repo/harness/code.yaml path. Current examples elsewhere in the repo (docs/guides/user/customizing-agents.md, docs/guides/user/customizing-overview.md) point the same base: example at fullsend-ai/agents's harness/code.yaml instead, and internal/scaffold/fullsend-repo/ no longer has a harness/ subdirectory (only providers/, templates/, scripts/, profiles/, .github/ remain). This stale reference predates this PR, but the PR moves/edits this exact file without correcting it, and the PR's own subject (the agents/fullsend repo split) makes this a directly on-topic omission.
    Remediation: Update the Level 3 example's base: URL to point at the fullsend-ai/agents repo's harness/code.yaml, matching docs/guides/user/customizing-agents.md and docs/guides/user/customizing-overview.md.


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

Review

Findings

Medium

  • [logic-error] Makefile:184 — The new lychee exclusion --exclude-path ^_agents/ will not skip the agents submodule. lychee's --exclude-path is a path/glob matcher (the working in-repo pattern is --exclude-path experiments, with no regex anchors). A leading ^ is a literal character, so the matcher looks for a path starting with ^_agents/ and never hits _agents/. --exclude-path docs/agents/ only covers the symlink walk, not the real tree: lint-md-links globs '**/*.md', which also discovers _agents/**/*.md (skills, READMEs, and other markdown outside _agents/docs/) once the submodule is initialized. Those files are not part of this repo's link graph, so make lint-md-links will scan/flag content this PR meant to exclude. This exact bug was present at the prior review's commit too and was not fixed in this revision.
    Remediation: Replace --exclude-path ^_agents/ with --exclude-path _agents, matching the existing --exclude-path experiments form. Keep --exclude-path docs/agents/ if the symlink path should also stay excluded separately.

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, CODEOWNERS, skills/author-fullsend-augmentations/SKILL.md — This PR modifies 4 protected governance/infrastructure files: adds a submodule-init step to the default CI job in lint.yml, adds _agents path triggers to site-build.yml, adds a blank-owner CODEOWNERS entry for _agents, and updates path references in the augmentations skill. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and its description explains the rationale (surfacing fullsend-ai/agents docs on the site, following the existing experiments submodule pattern) consistently across these files. Human approval is always required for protected-path changes regardless of context.

Low

  • [logic-error] docs/doc-site.md:50 — The new sentence claims that local site builds and make lint may require a manual git submodule update --init, but this overstates what this same PR just automated: package.json's docs:dev/docs:build already run git submodule update --init, and the Makefile's ensure-hooks target (a prerequisite of make lint/make lint-all, also changed in this PR) now runs git submodule update --init _agents automatically when _agents is present but uninitialized.
    Remediation: Drop the make lint half of the manual-init sentence (it's now automatic via ensure-hooks), or narrow the sentence to cover only direct vitepress/other invocations that bypass the npm scripts and the Makefile.

  • [documentation-staleness] skills/filing-issues/SKILL.md:26 — CONTRIBUTING.md's new "Where to file agents-related issues" section defines a repository split (agent definitions/harness/skills/schemas inside fullsend-ai/agents vs. submodule-integration concerns in fullsend-ai/fullsend), but skills/filing-issues/SKILL.md was not updated to reflect it. Step 1 ("Identify the target repository") only defines the fullsend-ai/experiments vs fullsend-ai/fullsend split, and Step 2's duplicate-search instructions only mention searching both repos for experiments-related topics. An agent using this skill to file an agents-related issue will not be routed to fullsend-ai/agents. This file is not touched by this PR.
    Remediation: Update skills/filing-issues/SKILL.md to add the fullsend-ai/agents repository split (mirroring the experiments table) and extend Step 2's duplicate-search guidance to also search fullsend-ai/agents when the topic is agents-related.

  • [documentation-staleness] AGENTS.md:21 — AGENTS.md's "Experiments issues" bullet explains the experiments/fullsend filing split and points to CONTRIBUTING.md § Where to file experiments-related issues. This PR adds a parallel "Where to file agents-related issues" section to CONTRIBUTING.md but does not add a corresponding "Agents issues" bullet to AGENTS.md, so contributors and agents reading this file's topic guidance table will not discover the new policy. This file is not touched by this PR.
    Remediation: Add an "Agents issues" entry in AGENTS.md parallel to "Experiments issues", pointing to CONTRIBUTING.md § Where to file agents-related issues.

  • [documentation-staleness] docs/guides/user/escalation-ladder.md:77 — This page (moved in this PR from docs/agents/topics/escalation-ladder.md, with content edits) still says, in the "Level 2: Contribute to the default agent" section: "If the change is in the fullsend-ai/fullsend repo (harness, scripts, skills, agent definitions), contribute there. If the agent definition or harness lives in fullsend-ai/agents, contribute to that repo instead." This parenthetical's examples (harness, scripts, agent definitions living in fullsend-ai/fullsend) are stale relative to the repository split this same PR establishes in CONTRIBUTING.md, where harness YAML, scripts, schemas, and agent definitions live in fullsend-ai/agents (the _agents/ submodule) and fullsend-ai/fullsend owns submodule integration and docs/guides/user/ customization guides.
    Remediation: Update the Level 2 contribute paragraph in docs/guides/user/escalation-ladder.md so default-agent definitions, harnesses, scripts, and built-in skills are described as belonging in fullsend-ai/agents, consistent with the new CONTRIBUTING.md table.


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

Medium

  • [policy-coherence] CONTRIBUTING.md:187 — The new "Where to file agents-related issues" section is copied nearly verbatim from "Where to file experiments-related issues" but omits that section's caveat: **Status: proposed, pending maintainer confirmation.** with a tracking issue (Decide where to track issues for fullsend-ai/experiments work #588) noting a maintainer has not yet confirmed the de facto filing pattern as intended policy. The new agents section documents the same kind of de facto pattern (observed since _agents became a submodule) but asserts it as settled policy with no equivalent caveat or tracking issue — inconsistent with the project's own established precedent for exactly this kind of governance content.
    Remediation: Either add the same "Status: proposed, pending maintainer confirmation" caveat (with a tracking issue) to the new agents section, or get explicit maintainer sign-off in this PR before presenting it as settled policy.

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, CODEOWNERS, skills/author-fullsend-augmentations/SKILL.md — This PR modifies 4 protected governance/infrastructure files: adds a submodule-init step to the default CI job in lint.yml, adds _agents path triggers to site-build.yml, adds a blank-owner CODEOWNERS entry for _agents, and updates path references in the augmentations skill. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and its description explains the rationale (surfacing fullsend-ai/agents docs on the site, following the existing experiments submodule pattern) consistently across all four files. Human approval is always required for protected-path changes regardless of context.

Low

  • [logic-error] docs/doc-site.md:46 — The new sentence claims that local site builds and make lint may require a manual git submodule update --init, but this contradicts mechanisms this same PR wires up: package.json's docs:dev/docs:build already run git submodule update --init automatically, and the Makefile's ensure-hooks target (a prerequisite of make lint/make lint-all, also changed in this PR) now runs git submodule update --init _agents automatically.
    Remediation: Drop the make lint half of the manual-init sentence (it's now automatic via ensure-hooks), or narrow the sentence to cover only direct vitepress/other invocations that bypass the npm scripts and the Makefile.

  • [documentation-staleness] skills/filing-issues/SKILL.md:26 — CONTRIBUTING.md's new "Where to file agents-related issues" section defines a repository split (agent definitions/harness/skills/schemas inside fullsend-ai/agents vs. submodule-integration concerns in fullsend-ai/fullsend), but skills/filing-issues/SKILL.md was not updated to reflect it. Step 1 ("Identify the target repository") only defines the fullsend-ai/experiments vs fullsend-ai/fullsend split, and Step 2's duplicate-search instructions only mention searching both repos for experiments-related topics. An agent using this skill to file an agents-related issue will not be routed to fullsend-ai/agents. This file is not touched by this PR.
    Remediation: Update skills/filing-issues/SKILL.md to add the fullsend-ai/agents repository split (mirroring the experiments table) and extend Step 2's duplicate-search guidance to also search fullsend-ai/agents when the topic is agents-related.

  • [documentation-staleness] AGENTS.md:21 — AGENTS.md's "Experiments issues" bullet explains the experiments/fullsend filing split and points to CONTRIBUTING.md § Where to file experiments-related issues. This PR adds a parallel "Where to file agents-related issues" section to CONTRIBUTING.md but does not add a corresponding "Agents issues" bullet to AGENTS.md, so contributors and agents reading this file's topic guidance table will not discover the new policy. This file is not touched by this PR.
    Remediation: Add an "Agents issues" entry in AGENTS.md parallel to "Experiments issues", pointing to CONTRIBUTING.md § Where to file agents-related issues.

  • [documentation-staleness] docs/guides/user/escalation-ladder.md:77 — This page (moved in this PR from docs/agents/topics/escalation-ladder.md) still says, in the "Level 2: Contribute to the default agent" section: "If the change is in the fullsend-ai/fullsend repo (harness, scripts, skills, agent definitions), contribute there. If the agent definition or harness lives in fullsend-ai/agents, contribute to that repo instead." This contradicts the repository split this same PR establishes in CONTRIBUTING.md, where harness YAML, scripts, skills, and agent definitions live in fullsend-ai/agents (the _agents/ submodule), and fullsend-ai/fullsend only owns submodule integration and customization guides.
    Remediation: Update the Level 2 contribute paragraph in docs/guides/user/escalation-ladder.md so default-agent definitions, harnesses, scripts, and built-in skills are described as belonging in fullsend-ai/agents, consistent with the new CONTRIBUTING.md table.


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

Medium

  • [logic-error] Makefile:184 — The new lychee exclusion --exclude-path ^_agents/ will not skip the agents submodule. Lychee 0.24.2's --exclude-path matches a filesystem path/glob, not a regex — the working sibling exclusions are --exclude-path experiments and --exclude-path node_modules (no caret). ^ is not special to that matcher, so the pattern looks for a path literally starting with ^_agents/, which never matches _agents/**. --exclude-path docs/agents/ only covers the symlink view, not _agents/ itself. Combined with ensure-hooks now running git submodule update --init _agents, the standalone make lint-md-links target ('**/*.md', documented in make help) will walk into _agents/**/*.md unexcluded. CI itself is unaffected — make lint-all runs pre-commit with pass_filenames, which never traverses into the submodule/symlink — but a developer running make lint-md-links after this PR would get spurious link-check results from the submodule's docs.
    Remediation: Change --exclude-path ^_agents/ to --exclude-path _agents, matching --exclude-path experiments (no caret, no trailing slash).

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, CODEOWNERS, skills/author-fullsend-augmentations/SKILL.md — This PR modifies 4 protected governance/infrastructure files: adds a submodule-init step to the default CI job in lint.yml, adds _agents path triggers to site-build.yml, adds a blank-owner CODEOWNERS entry for _agents, and updates path references in the augmentations skill. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and its description explains the rationale (surfacing fullsend-ai/agents docs on the site, following the existing experiments submodule pattern) consistently across all four files. Human approval is always required for protected-path changes regardless of context.

Low

  • [logic-error] docs/doc-site.md:46 — The new sentence claims that local site builds and make lint may require a manual git submodule update --init, but the same paragraph already states docs:dev/docs:build initialize submodules automatically, and this PR's own Makefile change makes ensure-hooks (a prerequisite of make lint and make lint-all) run git submodule update --init _agents automatically. The manual-init guidance for make lint is stale as of this same PR.
    Remediation: Drop the make lint half of the manual-init sentence (it's now automatic via ensure-hooks), or narrow the sentence to cover only direct vitepress/other invocations that bypass the npm scripts and the Makefile.

  • [secret-exposure] .github/workflows/lint.yml:24 — Unchanged since the prior review. The default CI job (test, runs on every pull_request/push/merge_group, no path filter) checks out with actions/checkout default persist-credentials: true (the step has no with: block) and then runs git submodule update --init _agents. .gitmodules' URL and the _agents gitlink SHA are both PR-controlled, so every PR triggers a credentialed git fetch of a PR-chosen GitHub URL. Workflow permissions: contents: read is unchanged and the persisted credential is host-scoped to github.com, so this is hardening rather than a demonstrated token-exfiltration path — the same pattern already exists unmodified in site-build.yml.
    Remediation: Set persist-credentials: false on the actions/checkout step in the test job of lint.yml (the job never pushes) and let git submodule update --init _agents run unauthenticated for the public submodule.

  • [documentation-staleness] skills/filing-issues/SKILL.md:26 — CONTRIBUTING.md's new "Where to file agents-related issues" section defines a repository split (agent definitions/harness/skills/schemas inside fullsend-ai/agents vs. submodule-integration concerns in fullsend-ai/fullsend), but skills/filing-issues/SKILL.md was not updated to reflect it. Step 1 ("Identify the target repository") only defines the fullsend-ai/experiments vs fullsend-ai/fullsend split, and Step 2's duplicate-search instructions only mention searching both repos for experiments-related topics. An agent using this skill to file an agents-related issue will not be routed to fullsend-ai/agents. This file is not touched by this PR.
    Remediation: Update skills/filing-issues/SKILL.md to add the fullsend-ai/agents repository split (mirroring the experiments table) and extend Step 2's duplicate-search guidance to also search fullsend-ai/agents when the topic is agents-related.

  • [documentation-staleness] AGENTS.md:21 — AGENTS.md's "Experiments issues" bullet explains the experiments/fullsend filing split and points to CONTRIBUTING.md § Where to file experiments-related issues. This PR adds a parallel "Where to file agents-related issues" section to CONTRIBUTING.md but does not add a corresponding "Agents issues" bullet to AGENTS.md, so contributors and agents reading this file's topic guidance table will not discover the new policy. This file is not touched by this PR.
    Remediation: Add an "Agents issues" entry in AGENTS.md parallel to "Experiments issues", pointing to CONTRIBUTING.md § Where to file agents-related issues.


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 (4)

Review

Findings

Medium

  • [logic-error] CODEOWNERS:12 — The new blank-owner rule is _agents/ (trailing slash), unlike the existing submodule entries experiments and eval/.agent-eval-harness (no trailing slash). CODEOWNERS uses gitignore syntax: a pattern ending in / matches only a directory, not a regular file/gitlink entry. In the parent repo a submodule is a gitlink (mode 160000) at path _agents; Renovate SHA bumps only change that gitlink. If GitHub's CODEOWNERS matcher does not treat the gitlink as a directory, the last-match-wins blank owner never applies, so PRs touching this path stay owned by * @fullsend-ai/core and the stated goal (Renovate digest bumps auto-merge after CI) will not hold for this submodule.
    Remediation: Change the entry to _agents (no trailing slash), matching experiments and eval/.agent-eval-harness.

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, CODEOWNERS, skills/author-fullsend-augmentations/SKILL.md — This PR modifies 4 protected governance/infrastructure files: adds a submodule-init step to the default CI job in lint.yml, adds _agents path triggers to site-build.yml, adds a blank-owner CODEOWNERS entry for _agents/, and updates two path references in the augmentations skill. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and the rationale (surfacing fullsend-ai/agents docs on the site, following the existing experiments submodule pattern) is clear and consistent across all four files, but human approval is always required for protected-path changes regardless of context. Note: the submodule was renamed from agents to _agents since the prior review, so the submodule addition itself (_agents, .gitmodules, Makefile) no longer matches the agents/ entry in the active protected-paths list — the matched file count dropped from 5 (prior review) to 4 this run. This looks like an incidental effect of a legitimate technical rename (documented in-diff: avoiding Go's ./... walk into the submodule directory), not deliberate evasion.

Low

  • [secret-exposure] .github/workflows/lint.yml:24 — The default CI job (test, runs on every pull_request/push/merge_group, no path filter) checks out with actions/checkout default persist-credentials: true (not overridden) and then runs git submodule update --init _agents. .gitmodules' URL and the _agents gitlink SHA are both PR-controlled, so every PR triggers a credentialed git fetch of a PR-chosen GitHub URL. Workflow permissions: contents: read is unchanged and the persisted credential is host-scoped to github.com, so this is hardening rather than a demonstrated token-exfiltration path — the same pattern already exists unmodified in site-build.yml. Unchanged from the prior review (submodule renamed agents → _agents, but the underlying gap is identical).
    Remediation: Set persist-credentials: false on the actions/checkout step in the test job of lint.yml (the job never pushes) and let git submodule update --init _agents run unauthenticated for the public submodule.

  • [intent-alignment] CONTRIBUTING.md:170 — The existing "Where to file experiments-related issues" section (CONTRIBUTING.md:155) carries the caveat "Status: proposed, pending maintainer confirmation." and links issue Decide where to track issues for fullsend-ai/experiments work #588. The new "Where to file agents-related issues" section added by this PR mirrors that same filing-split pattern but is presented as settled fact, with no equivalent proposed/unconfirmed caveat or tracking issue.
    Remediation: Either link a tracking issue and mark the new section "Status: proposed, pending maintainer confirmation" (matching the experiments precedent), or get explicit maintainer sign-off before presenting it as settled.

  • [documentation-staleness] skills/filing-issues/SKILL.md:26 — CONTRIBUTING.md's new "Where to file agents-related issues" section defines a repository split (agent definitions/harness/skills/schemas inside fullsend-ai/agents vs. submodule-integration concerns in fullsend-ai/fullsend), but skills/filing-issues/SKILL.md was not updated to reflect it. Step 1 ("Identify the target repository") only defines the fullsend-ai/experiments vs fullsend-ai/fullsend split, and Step 2's duplicate-search instructions only mention searching both repos for experiments-related topics. An agent using this skill to file an agents-related issue will not be routed to fullsend-ai/agents.
    Remediation: Update skills/filing-issues/SKILL.md to add the fullsend-ai/agents repository split (mirroring the experiments table) and extend Step 2's duplicate-search guidance to also search fullsend-ai/agents when the topic is agents-related.

  • [documentation-staleness] AGENTS.md:21 — AGENTS.md's "Experiments issues" bullet explains the experiments/fullsend filing split and points to CONTRIBUTING.md § Where to file experiments-related issues. This PR adds a parallel "Where to file agents-related issues" section to CONTRIBUTING.md but does not add a corresponding "Agents issues" bullet to AGENTS.md, so contributors and agents reading this file's topic guidance table will not discover the new policy.
    Remediation: Add an "Agents issues" entry in AGENTS.md parallel to "Experiments issues", pointing to CONTRIBUTING.md § Where to file agents-related issues.

Info

  • [permission-reduction] CODEOWNERS:12 — New blank-owner CODEOWNERS entry for _agents/ drops the core-team review requirement for that path, mirroring the existing rationale for .gitmodules, experiments, and eval/.agent-eval-harness (Renovate gitlink bumps auto-merge after CI). Confirmed intentional and consistent with existing pattern; only the pattern syntax itself is questionable (see the logic-error finding above at the same location).

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 (5)

Review

Findings

Medium

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, .pre-commit-config.yaml, agents, skills/author-fullsend-augmentations/SKILL.md — This PR modifies 5 protected governance/infrastructure files (submodule init in the lint workflow, path triggers for the agents submodule in site-build, a lychee exclusion update, the new agents submodule reference, and a path update in the augmentations skill). The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and the rationale is clear, but human approval is always required for protected-path changes. (Unchanged from the prior review — same file set, same rationale.)

Low

  • [secret-exposure] .github/workflows/lint.yml:23 — The default CI job (test, runs on every pull_request, no path filter) now runs git submodule update --init agents right after actions/checkout, which defaults to persist-credentials: true. .gitmodules' URL and the agents gitlink SHA are both PR-controlled, so every PR now triggers a credentialed git fetch of a PR-chosen GitHub URL. The checkout's persisted credential extraheader is host-scoped to github.com and the workflow's permissions: contents: read is unchanged, so this is hardening rather than a demonstrated token-exfiltration path — the same persist-credentials + git submodule update --init pattern already exists, unmodified, in site-build.yml's build step. This PR does extend the pattern to the unfiltered default CI job that runs on every PR.
    Remediation: Set persist-credentials: false on the actions/checkout step in lint.yml (the job never pushes) and let git submodule update --init agents run unauthenticated for the public submodule.

  • [documentation-staleness] docs/guides/getting-started/configuring-github.md:127 — The "Next steps" section links to ../../agents/README.md. This PR deletes docs/agents/README.md from this repo and turns docs/agents into a symlink to ../agents/docs/ in the new submodule. Pages this PR did retarget to the agents reference use the directory form instead of a specific filename (e.g. docs/guides/user/customizing-with-agents-md.md now uses ../../agents/). This file, untouched by the PR, still uses the old specific-filename form — not a proven broken link (the submodule may still ship a README.md), but inconsistent with the link form used elsewhere in this same PR.
    Remediation: Update [Agents](../../agents/README.md) to [Agents](../../agents/), matching the directory form used on the pages this PR touched.

  • [documentation-staleness] docs/guides/getting-started/org-mode.md:207 — Same leftover ../../agents/README.md link as configuring-github.md:127 above, in the "Next Steps" section. (This page documents the deprecated per-org installation mode — the org-mode content itself is unrelated to this PR; only the coincidental stale link matters here.)
    Remediation: Update [Agents](../../agents/README.md) to [Agents](../../agents/).


Labels: PR restructures documentation delivery (new agents submodule, docs/agents symlink, sidebar auto-discovery) and modifies CI workflow files (lint.yml, site-build.yml); neither the docs nor CI component labels are currently applied.


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 (6)

Review

Findings

Medium

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, .pre-commit-config.yaml, agents, skills/author-fullsend-augmentations/SKILL.md — This PR modifies 5 protected governance/infrastructure files. The changes add agents submodule initialization to the lint workflow, add path triggers for the agents submodule to site-build, update lychee exclusion in pre-commit, add the agents submodule reference, and update path references in the augmentations skill. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and the rationale is clear, but human approval is always required for protected-path changes.

Low

  • [always-true-guard] Makefile:83 — The submodule initialization guard [ ! -d "agents/.git" ] in ensure-hooks (line 83) and bootstrap (line 49) never evaluates to false after initialization. In initialized git submodules, .git is a file (containing gitdir: ...), not a directory, so ! -d is always true. This causes git submodule update --init agents to run on every make lint invocation.
    Remediation: Use [ ! -e "agents/.git" ] instead of [ ! -d "agents/.git" ].

  • [scope-creep] docs/guides/user/escalation-ladder.md:22 — The escalation-ladder.md file undergoes a content modification during the rename: the ‘four levels’ monospace code block is reformatted into a numbered markdown list. This formatting change is not described in the PR body.
    Remediation: Either revert the code-block-to-list reformatting or describe the content change explicitly in the PR body.

  • [sidebar-items-lost] docs/.vitepress/config.ts:255 — getMarkdownFiles('agents', 'agents') only discovers top-level .md files and immediate subdirectories with README.md. If the agents submodule’s docs/ later adds nested directories with content pages, those would be silently omitted. This matches the existing experiments sidebar section behavior.


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

High

  • [stale-doc] docs/guides/user/default-vs-custom-agents.md:46 — The relative link (../) was correct in the old location docs/agents/topics/ where ../ resolved to docs/agents/. After the rename to docs/guides/user/, ../ resolves to docs/guides/ — the guides index — not the agents reference. The inline text explicitly says "docs/agents/<agent>.md" making the mismatch obvious to readers.
    Remediation: Change ../ to ../../agents/ so the link correctly points to the agents reference documentation.

  • [stale-doc] docs/guides/user/default-vs-custom-agents.md:93 — The "See also" entry [Agents reference](../) has the same broken relative path. From docs/guides/user/, ../ resolves to docs/guides/ instead of docs/agents/.
    Remediation: Change ../ to ../../agents/ on the Agents reference see-also entry.

  • [stale-doc] docs/guides/user/escalation-ladder.md:45 — The table cell Each agent's [reference page](../) has a broken relative path. The file was moved from docs/agents/topics/ (where ../ = docs/agents/) to docs/guides/user/ (where ../ = docs/guides/). The PR updated sibling-relative links in this file but missed this parent-directory link.
    Remediation: Change ../ to ../../agents/ so the link correctly points to the agents reference documentation.

Medium

  • [stale-reference] skills/author-fullsend-augmentations/SKILL.md:253 — Two references to docs/agents/topics/default-vs-custom.md remain in this file (lines 253 and 314). The PR removes the docs/agents/topics/ directory entirely — docs/agents is now a symlink to ../agents/docs/, and the topics/ subdirectory does not exist in the agents submodule. The file was moved to docs/guides/user/default-vs-custom-agents.md. These paths will be broken after merge.
    Remediation: Update both occurrences to docs/guides/user/default-vs-custom-agents.md.

  • [inconsistent-lychee-exclusion] Makefile:180 — The Makefile lychee invocation uses --exclude-path ^agents/ but does NOT include --exclude-path docs/agents/. Since docs/agents is now a symlink to ../agents/docs/, the glob '**/*.md' will follow the symlink and discover markdown files under docs/agents/. Those paths start with docs/agents/, which do not match the ^agents/ regex. The pre-commit config correctly adds --exclude-path docs/agents/ but the Makefile does not.
    Remediation: Add --exclude-path docs/agents/ to the Makefile lychee invocation.

  • [naming-convention] docs/.vitepress/config.ts:272 — The two new sidebar entries (lines 272 and 274) carry .md extensions in their link values (/guides/user/default-vs-custom-agents.md and /guides/user/escalation-ladder.md). All other sidebar links — including those produced by getMarkdownFiles and all ~30 hardcoded entries — omit the extension. VitePress resolves both forms, but this violates the established codebase convention.
    Remediation: Remove the .md suffix from both link values.

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, .pre-commit-config.yaml, agents — This PR modifies 4 protected governance/infrastructure files. The changes add agents submodule initialization to the lint workflow, add path triggers for the agents submodule to site-build, update lychee exclusion in pre-commit, and add the agents submodule reference. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and the rationale is clear, but human approval is always required for protected-path changes.

Low

  • [sidebar-items-lost] docs/.vitepress/config.ts:255 — getMarkdownFiles('agents', 'agents') only discovers top-level .md files and immediate subdirectories with README.md. If the agents submodule's docs/ later adds nested directories with content pages, those would be silently omitted. This matches the existing experiments sidebar section behavior.

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 (8)

Review

Findings

Medium

  • [stale-reference] skills/author-fullsend-augmentations/SKILL.md:253,314 — Two references to docs/agents/topics/default-vs-custom.md remain in this file (lines 253 and 314). The PR removes docs/agents/topics/ entirely — the docs/agents directory is now a symlink to ../agents/docs/, and the topics/ subdirectory does not exist in the agents submodule. The file was moved to docs/guides/user/default-vs-custom-agents.md. These paths will be broken after merge.
    Remediation: Update both occurrences to docs/guides/user/default-vs-custom-agents.md.

  • [inconsistent-lychee-exclusion] Makefile:180 — The Makefile's lychee exclusion uses --exclude-path ^agents/ (regex anchored to start-of-path), which correctly excludes files directly under agents/ but does NOT exclude files reached through the docs/agents symlink (which resolves to paths like docs/agents/code.md). The Makefile passes '**/*.md' as a literal glob to lychee, which follows symlinks during traversal. Files discovered via the symlink will have paths starting with docs/agents/, not agents/, so they bypass the ^agents/ exclusion. The pre-commit config separately adds --exclude-path docs/agents/ but not ^agents/.
    Remediation: Add --exclude-path docs/agents/ to the Makefile lychee invocation (in addition to the existing ^agents/). Optionally add --exclude-path ^agents/ to pre-commit for symmetry.

  • [naming-convention] docs/.vitepress/config.ts:270 — The two new sidebar entries use .md extensions in their link values (/guides/user/default-vs-custom-agents.md, /guides/user/escalation-ladder.md). These are the only two sidebar links in the entire file that include the .md extension — all other links (~30+) omit it. VitePress resolves both forms, so this is not a functional bug, but it violates the established codebase convention.
    Remediation: Remove the .md suffix from both new link values: /guides/user/default-vs-custom-agents and /guides/user/escalation-ladder.

  • [protected-path] .github/workflows/lint.yml, .github/workflows/site-build.yml, .pre-commit-config.yaml — This PR modifies 3 protected governance/infrastructure files. The changes add agents submodule initialization to the lint workflow, add path triggers for the agents submodule to site-build, and exclude symlinked agent docs from lychee link checking. The PR links to issue Include fullsend-ai/agents docs in the documentation site #5710 and the rationale is clear, but human approval is always required for protected-path changes.

Low

  • [sidebar-items-lost] docs/.vitepress/config.ts:255 — getMarkdownFiles('agents', 'agents') only discovers top-level .md files and immediate subdirectories with README.md. Currently, all agent docs in the submodule are top-level and correctly represented. If the agents submodule's docs/ later adds nested directories with content pages (not just README.md), those would be silently omitted from the sidebar.

Next steps:

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

fullsend-ai-review[bot]

This comment was marked as outdated.

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional review finding (posted programmatically, deduplicated against existing comments):

Comment thread docs/doc-site.md Resolved
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 7, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:49 AM UTC · Completed 9:12 AM UTC

Commit: 9b83535 · View workflow run →

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

fullsend-ai-review[bot]

This comment was marked as outdated.

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 7, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 9:39 AM UTC · Completed 9:58 AM UTC

Commit: a503979 · View workflow run →

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

fullsend-ai-review[bot]

This comment was marked as outdated.

@rh-hemartin

This comment was marked as off-topic.

fullsend-ai-review[bot]

This comment was marked as outdated.

fullsend-ai-review[bot]

This comment was marked as outdated.

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review-only pass (no approval, no change request). Findings verified against head 516b44d9 and deduplicated against the existing comments on this PR. One finding is inline; the one below is commit-level and has no line in the diff to anchor to.


[MEDIUM] Branch commit is typed feat(docs) but COMMITS.md reserves feat for user-facing functionality; it will land under Features in the release notes

The single branch commit 516b44d and the PR title are feat(docs): pull agent documentation from fullsend-ai/agents. COMMITS.md (which says reviewers "must consult this file") defines feat as "New user-facing functionality" (line 19) and docs as "Documentation only" (line 22), gives docs: add mint URL stability note to installation guide as a worked example (line 109), and states "When in doubt, prefer refactor or chore over feat or fix ... A change miscategorized as feat erodes the signal of the Features list" (line 47).

.goreleaser.yml:45-48 groups ^.*?feat(...)?: under Features and excludes ^docs/^chore/^ci/^build entirely, and the main ruleset's merge queue uses merge_method: MERGE, so GoReleaser will read the branch commit's title (not a squash title) — retitling the PR alone does not fix it.

The diff adds no capability an end user invokes: it adds the _agents submodule + docs/agents symlink, sidebar auto-discovery, Makefile/lint.yml/site-build.yml/CODEOWNERS/CONTRIBUTING wiring, and moves two guides. gitlint (.gitlint contrib CT1) only checks that the type is in the allowed list, so nothing in CI catches the misclassification. The PR body's "[x] PR title follows Conventional Commits (correct type)" box is ticked.

Suggested fix: amend the branch commit (and PR title) to chore(docs): pull agent documentation from fullsend-ai/agents — chore fits best since the change spans CI, Makefile, CODEOWNERS and submodule wiring, not documentation text alone; plain docs: per the COMMITS.md:109 example is also acceptable. Either keeps it out of the Features section per .goreleaser.yml.

Comment thread docs/.vitepress/config.ts Resolved
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Started 9:26 AM UTC · Ended 9:36 AM UTC

Commit: 6aa7b15 · View workflow run →

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 9:38 AM UTC · Completed 9:59 AM UTC

Commit: f194582 · View workflow run →

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

fullsend-ai-review[bot]

This comment was marked as outdated.

fullsend-ai-review[bot]

This comment was marked as outdated.

@rh-hemartin rh-hemartin changed the title feat(docs): pull agent documentation from fullsend-ai/agents chore(docs): pull agent documentation from fullsend-ai/agents Sep 21, 2026
Add fullsend-ai/agents as a submodule and link its docs/
folder into docs/agents, so the contents are fresh from
that repository. Rebuild the docs site when the agents
submodule changes, matching the experiments/ path filters.

There will be a drift as the submodule gets updated, but
we can deal with that later.

Assisted-By: Grok 4.6 (Pi runtime)
Signed-off-by: Hector Martinez <hemartin@redhat.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 21, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:05 AM UTC · Completed 6:29 AM UTC

Commit: 4b59000 · View workflow run →

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

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: The following review comments could not be posted on the diff (GitHub returned 422) and are included here instead:

  • docs/guides/user/escalation-ladder.md (file-level): Line 78 · [low] documentation-staleness

In 'Level 2: Contribute to the default agent,' the how-to-contribute paragraph still says: if the change is in fullsend-ai/fullsend (harness, scripts, skills, agent definitions), contribute there; if the agent definition or harness lives in fullsend-ai/agents, contribute there instead. That first branch's examples (harness, scripts, agent definitions living in fullsend-ai/fullsend) are stale relative to the repository split this same PR establishes in CONTRIBUTING.md, where those live in fullsend-ai/agents (the _agents/ submodule).

Suggested fix: Update the Level 2 contribute paragraph so default-agent definitions, harnesses, scripts, and built-in skills are described as belonging in fullsend-ai/agents, consistent with the new CONTRIBUTING.md table.

  • docs/guides/user/escalation-ladder.md (file-level): Line 109 · [low] documentation-staleness

The Level 3 example still uses a base: URL pointing into fullsend-ai/fullsend's internal/scaffold/fullsend-repo/harness/code.yaml path. Current examples elsewhere in the repo (docs/guides/user/customizing-agents.md, docs/guides/user/customizing-overview.md) point the same base: example at fullsend-ai/agents's harness/code.yaml instead, and internal/scaffold/fullsend-repo/ no longer has a harness/ subdirectory (only providers/, templates/, scripts/, profiles/, .github/ remain). This stale reference predates this PR, but the PR moves/edits this exact file without correcting it, and the PR's own subject (the agents/fullsend repo split) makes this a directly on-topic omission.

Suggested fix: Update the Level 3 example's base: URL to point at the fullsend-ai/agents repo's harness/code.yaml, matching docs/guides/user/customizing-agents.md and docs/guides/user/customizing-overview.md.

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review comment for full details.

Comment thread Makefile Resolved
Comment thread docs/doc-site.md Resolved
Comment thread .github/workflows/lint.yml Resolved
Comment thread CONTRIBUTING.md Resolved
@rh-hemartin

Copy link
Copy Markdown
Member Author

This is taking too much to merge, will look for an alternative

@rh-hemartin rh-hemartin closed this Oct 7, 2026
@rh-hemartin
rh-hemartin deleted the feat/inject-agents branch October 7, 2026 07:34
@fullsend-ai-retro

fullsend-ai-retro Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

🤖 Finished Retro · ✅ Success · Started 7:35 AM UTC · Completed 7:44 AM UTC

Commit: 4b59000 · View workflow run →

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

@fullsend-ai-retro

Copy link
Copy Markdown

PR #6953 (vendor fullsend-ai/agents docs via submodule, closing #5710) was never merged — the human author closed it after 18 days, 12 force-pushes, and 10 successful review passes plus 3 cancelled ones, citing it was "taking too much to merge." The review agent (resolved from fullsend-ai/agents@v0.40.0) correctly required human approval on every pass because the PR touched protected paths (CI workflow filters, CODEOWNERS); that gate was legitimate, but the pipeline never adapted to the resulting churn. Three review runs (Sep 3, 10, 18) were cancelled mid-flight by GitHub Actions concurrency preemption when the author pushed a new commit while a ~15-20 min review was still running — this is already extensively tracked as open issues #1014 and #7314 (debounce review dispatch on rapid pushes); this run adds a third confirming data point (3/13 dispatches cancelled this way). A human reviewer (waynesun09) also independently caught a conventional-commit-type miscategorization (feat(docs) should have been chore/docs per COMMITS.md, affecting GoReleaser changelog grouping) that the bot missed across all 10 of its passes — this is evidence for the already-open fullsend-ai/agents#1114 (review agent should flag non-conventional commit messages) and #1036 (verify remediation type against COMMITS.md), so no new issue filed for it. Two gaps had no existing coverage and are proposed below: (1) the review agent never checked whether a newly-added top-level path/submodule needed a corresponding CODEOWNERS entry — a human caught this manually; and (2) the review agent's risk-assessment stayed pinned at the same generic "moderate" note through all 10 passes over 18 days without ever escalating that the PR was structurally stuck behind a protected-path human-approval gate it could not itself resolve, which likely contributed to author attrition.

Proposals filed

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 4b590007 Deployed Sep 21, 2026 by github-actions[bot]
dev — 4b590007 Deployed Sep 21, 2026 by rh-hemartin via behaviour #13389
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/ci CI pipelines and checks component/docs User-facing documentation risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Include fullsend-ai/agents docs in the documentation site

2 participants