feat(docs): pull agent documentation from fullsend-ai/agents - #6953
feat(docs): pull agent documentation from fullsend-ai/agents#6953rh-hemartin wants to merge 1 commit into
Conversation
|
🤖 Review · Commit: |
PR Summary by QodoSource agent docs from the fullsend-ai/agents submodule
AI Description
Diagram
High-Level Assessment
Files changed (7)
|
Code Review by Qodo
1. Moved guides omit prerequisites
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| text: "Default, derived and custom agents", | ||
| link: "/guides/user/default-vs-custom-agents.md", | ||
| }, | ||
| { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" }, |
There was a problem hiding this comment.
1. Moved guides omit prerequisites 📜 Skill insight ✧ Quality
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.
Agent Prompt
## 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
| text: "Default, derived and custom agents", | ||
| link: "/guides/user/default-vs-custom-agents.md", | ||
| }, | ||
| { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" }, |
There was a problem hiding this comment.
2. escalation-ladder procedure is unnumbered 📜 Skill insight ✧ Quality
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.
Agent Prompt
## 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
| { | ||
| text: "Default, derived and custom agents", | ||
| link: "/guides/user/default-vs-custom-agents.md", | ||
| }, | ||
| { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" }, |
There was a problem hiding this comment.
3. New guides missing index entries 📜 Skill insight ⚙ Maintainability
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.
Agent Prompt
## 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
| { | ||
| text: "Default, derived and custom agents", | ||
| link: "/guides/user/default-vs-custom-agents.md", | ||
| }, | ||
| { text: "Agent escalation ladder", link: "/guides/user/escalation-ladder.md" }, |
There was a problem hiding this comment.
4. Moved guide links are broken 📜 Skill insight ≡ Correctness
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.
Agent Prompt
## 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
| - upstream-org/specific-repo | ||
| ``` | ||
|
|
||
| **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. |
There was a problem hiding this comment.
5. Per-org removal unmentioned 📘 Rule violation § Compliance
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.
| @@ -0,0 +1 @@ | |||
| ../agents/docs/ No newline at end of file | |||
There was a problem hiding this comment.
6. Moved pages break inbound links 🐞 Bug ≡ Correctness
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.
Agent Prompt
## 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
Site previewPreview: https://9a9fa37c-site.fullsend-ai.workers.dev Commit: |
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. Signed-off-by: Hector Martinez <hemartin@redhat.com> Assisted-By: Grok 4.6 (Pi runtime) Signed-off-by: Hector Martinez <hemartin@redhat.com>
f7c716f to
229fa6f
Compare
|
🤖 Finished Review · ✅ Success · Started 10:41 AM UTC · Completed 11:02 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $7.18 |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
Risk Assessment: moderate (2/5) DetailsModerate 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. |
ReviewFindingsMedium
Low
Next steps:
|
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
|
|
||
| lint-md-links: | ||
| lychee --offline --no-progress --include-fragments --exclude-path node_modules --exclude-path experiments --exclude-path docs/archived-roadmap.md '**/*.md' | ||
| lychee --offline --no-progress --include-fragments --exclude-path node_modules --exclude-path experiments --exclude-path ^agents/ --exclude-path docs/archived-roadmap.md '**/*.md' |
There was a problem hiding this comment.
[medium] inconsistent-lychee-exclusion
The Makefile's lychee exclusion uses --exclude-path ^agents/ (regex anchored to start-of-path), which correctly excludes files under agents/ but does NOT exclude files reached through the docs/agents symlink. Files discovered via the symlink have paths starting with docs/agents/, bypassing the ^agents/ exclusion.
Suggested fix: Add --exclude-path docs/agents/ to the Makefile lychee invocation in addition to the existing ^agents/.
| collapsed: true, | ||
| items: [ | ||
| { text: "Overview", link: "/guides/user/customizing-overview" }, | ||
| { |
There was a problem hiding this comment.
[medium] naming-convention
The two new sidebar entries use .md extensions in their link values (/guides/user/default-vs-custom-agents.md, /guides/user/escalation-ladder.md). All other sidebar links (~30+) in this file omit the .md extension. VitePress resolves both forms, but this violates the established codebase convention.
Suggested fix: Remove the .md suffix from both new link values: /guides/user/default-vs-custom-agents and /guides/user/escalation-ladder.
| { text: "Default vs. Custom", link: "/agents/topics/default-vs-custom" }, | ||
| { text: "Escalation Ladder", link: "/agents/topics/escalation-ladder" }, | ||
| ], | ||
| items: getMarkdownFiles("agents", "agents"), |
There was a problem hiding this comment.
[low] sidebar-items-lost
getMarkdownFiles('agents', 'agents') only discovers top-level .md files and immediate subdirectories with README.md. Currently all agent docs are top-level and correctly represented. If the agents submodule later adds nested content directories, those would be silently omitted from the sidebar.
waynesun09
left a comment
waynesun09
left a comment
There was a problem hiding this comment.
Additional review finding (posted programmatically, deduplicated against existing comments):
| | [fullsend-ai/experiments](https://github.com/fullsend-ai/experiments) | `experiments/` | `docs/experiments` -> `../experiments` | | ||
| | [fullsend-ai/agents](https://github.com/fullsend-ai/agents) | `agents/` | `docs/agents` -> `../agents/docs/` | | ||
|
|
||
| The `docs:dev` and `docs:build` scripts in the root `package.json` handle submodule initialization automatically. CI checkout in `.github/workflows/site-build.yml` uses `fetch-tags: true` and `fetch-depth: 0`; `git submodule update --init` runs in the build step. |
There was a problem hiding this comment.
[MEDIUM] make bootstrap/make ensure-hooks never init the new agents submodule, so a fresh clone's first commit fails lint-broken-symlinks
docs/agents is now a symlink (git mode 120000) to ../agents/docs/, which only resolves once the agents submodule is checked out. Verified on the PR head (229fa6f): .pre-commit-config.yaml wires lint-broken-symlinks with always_run: true, and that script (hack/lint-broken-symlinks) fails the hook whenever any git-tracked symlink is not resolvable on disk ([[ ! -e "$symlink" ]]). Neither make bootstrap (Makefile:47) nor make ensure-hooks (Makefile:78, which pre-commit installs and is a prerequisite of make lint) runs git submodule update --init, so a contributor who clones the repo, runs make bootstrap, and then makes their first commit hits a confusing pre-commit failure until they manually discover and run git submodule update --init agents.
This is a real, narrower gap than a generic "submodule not initialized" framing: this Submodules table (added by this PR, right above) already documents the agents submodule and correctly states that the docs:dev/docs:build npm scripts auto-init submodules — CI's lint.yml also explicitly inits it. The gap is specifically in the make-based bootstrap/pre-commit path, which isn't mentioned here as needing the same submodule init.
Suggestion: either have make bootstrap / make ensure-hooks run git submodule update --init agents (or --init for all submodules), or add a one-line note in this Submodules section that make lint / committing via pre-commit hooks also requires initializing the submodule, since only the npm docs scripts do it automatically today.
2 participants
Summary
Add
fullsend-ai/agentsas a git submodule and serve itsdocs/folder fromdocs/agentson the documentation site, so agent pages stay in sync with the agents repo instead of being copied by hand.Related Issue
Closes #5710
Changes
agentssubmodule at the repo root and replacedocs/agentswith a symlink toagents/docsgetMarkdownFilesdocs/guides/user/agents/changes, matching the existingexperiments/path filtersTesting
make lintpasses (stage changes first, then run)Checklist
!for breaking changes)