Skip to content

docs(#6030): add doc-update guidance for new CLI command additions - #6031

Closed
fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/6030-agents-md-doc-guidance
Closed

fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/6030-agents-md-doc-guidance

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Add symmetric doc-update guidance for CLI command additions to AGENTS.md. The existing rule covers removals and renames but not additions, which caused the code agent on PR #6022 to miss 5 documentation files when adding mint delete.

Changes

  • Add a new bullet to AGENTS.md instructing agents to grep docs/ for sibling subcommand references when adding a new CLI subcommand or public API endpoint, and update every file that enumerates the parent command's subcommands

Testing

  • Verified new bullet exists in AGENTS.md (grep -q 'adding a new CLI subcommand')
  • Verified sibling-command grep pattern is included
  • Verified existing removal/rename bullet is preserved
  • gitlint --commit HEAD passes

Note: pre-commit could not run (sandbox network policy blocks git fetch). Manual pre-commit verification is required.


Closes #6030

Post-script verification

  • Branch is not main/master (agent/6030-agents-md-doc-guidance)
  • Secret scan passed (gitleaks — 743f99d88b883f61b19f09d00b723f7a3f8ae4f8..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

AGENTS.md already instructs agents to grep docs when removing or
renaming CLI commands, but had no symmetric rule for additions.
This caused the code agent on PR #6022 to miss 5 documentation
files that enumerate mint subcommands when adding `mint delete`.

Add a new bullet alongside the existing removal/rename guidance
that tells agents to grep `docs/` for sibling subcommands when
adding a new CLI subcommand or public API endpoint and update
every file that enumerates the parent command's subcommands.

Closes #6030
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team August 10, 2026 10:43
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Aug 10, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 10:44 AM UTC · Completed 10:55 AM UTC

Commit: 0fa1e5a · View workflow run →

@codecov

codecov Bot commented Aug 10, 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 Aug 10, 2026 •

Copy link
Copy Markdown

Review

Findings

Medium

  • [stale branch / merge conflict] AGENTS.md:20 — The PR was branched from an older commit. The removal/rename rule on current main has since been updated to "When removing, renaming, or changing the behavior or output format of a CLI command..." (broader scope), and additional bullet points have been added between this rule and the "## Topic-specific guidance" heading. The diff context no longer matches main, so a merge conflict is certain. During conflict resolution, the new addition line could be lost or misplaced.

  • [protected-path] AGENTS.md — This PR modifies AGENTS.md, a governance file under protected paths. The PR is linked to issue AGENTS.md: add doc-update guidance for new CLI command additions #6030, which provides clear rationale for the change (adding symmetric doc-update guidance for CLI command additions, motivated by the incident in PR feat(#2680): add mint delete command to tear down mint infrastructure #6022). Human approval is always required for protected-path changes, regardless of context.

Low

  • [architectural-coherence] AGENTS.md:20 — The new addition-guidance bullet references docs/guides/dev/cli-internals.md as a specific callout that is absent from the sibling removal/rename rule. This asymmetry is minor but worth noting for future alignment.
Previous run

Review

Findings

Medium

Low

  • [naming-consistency] AGENTS.md:20 — The phrase "command-tree docs" is informal shorthand rather than a concrete path. While "command tree" is used in the codebase (docs/cli/README.md, docs/cli/mint.md, docs/cli/inference.md all reference "command tree"), it refers to the CLI internals guide at docs/guides/dev/cli-internals.md. The term is understandable in context but less precise than the path-based references on the preceding line. Consider replacing with a concrete reference such as docs/guides/dev/cli-internals.md.

Labels: PR modifies AGENTS.md (meta-docs/conventions), which follows the repo convention of the documentation label without component/docs.

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added requires-manual-review Review requires human judgment documentation labels Aug 10, 2026
@rh-hemartin

Copy link
Copy Markdown
Member

/fs-fix

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 8:30 AM UTC · Completed 8:35 AM UTC

Commit: 0fa1e5a · View workflow run →

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

Replace 'command-tree docs' with 'docs/guides/dev/cli-internals.md'
in the new CLI subcommand guidance bullet for naming consistency
with other path-based references in the same section.

Addresses review feedback on #6031
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (human-triggered)

Addressed 1 of 2 review findings. Fixed naming-consistency by replacing informal 'command-tree docs' with the concrete path 'docs/guides/dev/cli-internals.md'. The protected-path finding is informational (human approval required) and does not require a code change.

Fixed (1):

  1. naming-consistency: 'command-tree docs' is informal shorthand (AGENTS.md): Replaced informal 'command-tree docs' with the concrete path reference 'docs/guides/dev/cli-internals.md' for consistency with the path-based references used elsewhere in the same section.

Disagreed (1):

  1. protected-path: AGENTS.md is a governance file under protected paths: This is an informational finding, not a code change request. The reviewer correctly notes that human approval is required for protected-path changes. No code fix is needed — the PR already requires human approval per repo policy.

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

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 26, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:36 AM UTC · Completed 8:52 AM UTC

Commit: e77280f · View workflow run →

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

@rh-hemartin

Copy link
Copy Markdown
Member

/fs-fix rebase and solve conflicts

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ❌ Failure (post-script /home/runner/work/fullsend/fullsend/.fullsend/.fullsend-cache/resources/sha256/1704f826be06352c5aa727ca7a68e6bc3db1837e9743e1727323664169eefe2b/scripts/post-fix.sh failed: exit status 1) · Started 8:40 AM UTC · Completed 8:46 AM UTC

Commit: e77280f · View workflow run →

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

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

⚠️ Post-fix script failed — Secret scan blocked (exit code 1)

The fix agent completed, but the post-fix script failed before finishing.

Workflow run: https://github.com/fullsend-ai/fullsend/actions/runs/32948816895

Details:
Secret scan blocked the push. See workflow logs for details.
Please check the workflow logs for full details and retry with /fs-fix if appropriate.

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Aug 26, 2026
@fullsend-ai-review

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Tiny additive-only documentation change (1 file, 1 line) by a bot author to a protected path (AGENTS.md). Low metadata risk elevated slightly by high file churn history.

@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 AGENTS.md
- Never commit secrets (tokens, API keys, PEM keys, gcloud credentials) or sensitive data (GCP project names, service account identifiers, Model Armor template names, internal hostnames). Use environment variables with no defaults for sensitive values.
- When adding a new doc under `docs/`, check `docs/.vitepress/config.ts` sidebar config. Sections using `getMarkdownFiles()` are auto-discovered. All other sections need a manual `{ text, link }` entry. Also add the new folder's prefix to `search.options.scopes` in the same file so the folder's pages are reachable when search scope pills are active.
- When removing or renaming a CLI command, public API, or user-facing feature, grep all documentation files under `docs/` for references to the old name and update or remove them. Pay special attention to `docs/cli/`, `docs/guides/`, and any getting-started or operations guides that walk through the removed workflow.
- When adding a new CLI subcommand or public API endpoint, grep `docs/` for references to sibling subcommands or endpoints (e.g., when adding `mint delete`, search for `mint deploy`) and add documentation to every file that enumerates the parent command's subcommands or the API's endpoints. Pay special attention to `docs/cli/`, `docs/guides/dev/cli-internals.md`, operations guides, and infrastructure references.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[medium] stale branch / merge conflict

The PR was branched from an older commit. The removal/rename rule on current main has since been updated to include or changing the behavior or output format and additional bullet points have been added between this rule and the Topic-specific guidance heading. The diff context no longer matches main, so a merge conflict is certain. During conflict resolution, the new addition line could be lost or misplaced.

Suggested fix: Rebase the PR branch onto current main before merging. Place the new addition line after the updated removal/rename rule.

Comment thread AGENTS.md
- Never commit secrets (tokens, API keys, PEM keys, gcloud credentials) or sensitive data (GCP project names, service account identifiers, Model Armor template names, internal hostnames). Use environment variables with no defaults for sensitive values.
- When adding a new doc under `docs/`, check `docs/.vitepress/config.ts` sidebar config. Sections using `getMarkdownFiles()` are auto-discovered. All other sections need a manual `{ text, link }` entry. Also add the new folder's prefix to `search.options.scopes` in the same file so the folder's pages are reachable when search scope pills are active.
- When removing or renaming a CLI command, public API, or user-facing feature, grep all documentation files under `docs/` for references to the old name and update or remove them. Pay special attention to `docs/cli/`, `docs/guides/`, and any getting-started or operations guides that walk through the removed workflow.
- When adding a new CLI subcommand or public API endpoint, grep `docs/` for references to sibling subcommands or endpoints (e.g., when adding `mint delete`, search for `mint deploy`) and add documentation to every file that enumerates the parent command's subcommands or the API's endpoints. Pay special attention to `docs/cli/`, `docs/guides/dev/cli-internals.md`, operations guides, and infrastructure references.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[low] architectural-coherence

The new addition-guidance bullet references docs/guides/dev/cli-internals.md as a specific callout that is absent from the sibling removal/rename rule. This asymmetry is minor but worth noting for future alignment.

Suggested fix: Consider whether docs/guides/dev/cli-internals.md should also be mentioned in the removal/rename rule for symmetry.

@rh-hemartin

Copy link
Copy Markdown
Member

Closing, complications.

@fullsend-ai-retro

fullsend-ai-retro Bot commented Aug 26, 2026 •

Copy link
Copy Markdown

🤖 Finished Retro · ✅ Success · Started 8:57 AM UTC · Completed 9:11 AM UTC

Commit: e77280f · View workflow run →

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

@fullsend-ai-retro

Copy link
Copy Markdown

Retro Analysis: PR #6031

Outcome: Closed without merging after 16 days idle and two fix iterations. A 1-line documentation change to AGENTS.md was abandoned due to cascading complications from branch staleness and a known post-script bug.

Timeline

  1. Aug 10 — Issue #6030 created by retro agent proposing symmetric doc-update guidance for CLI command additions in AGENTS.md.
  2. Aug 10 — Code agent creates PR #6031 with a single-line addition. Review agent finds [medium] protected-path (informational) and [low] naming-consistency ("command-tree docs" should be a concrete path).
  3. 16 days idle — PR awaits manual review (requires-manual-review due to protected path). During this period, AGENTS.md is substantially rewritten on main via PR fix(#6299): detect zero-test-file packages in coverage skill #6301.
  4. Aug 26 08:28 — Human triggers /fs-fix. Fix agent successfully replaces informal phrasing with concrete path docs/guides/dev/cli-internals.md. Post-script passes (scanned ~2 agent commits).
  5. Aug 26 08:36 — Re-review correctly identifies [medium] stale-branch/merge-conflict — main has diverged significantly.
  6. Aug 26 08:38 — Human triggers /fs-fix rebase and solve conflicts. Fix agent completes rebase (exit 0), but post-script gitleaks scan blocks push: 684 commits scanned, 6 false-positive leaks from main's history.
  7. Aug 26 08:55 — Human closes PR: "Closing, complications."

Evidence for existing issues

Workflow quality assessment

  • Review agent: Performed well. Correctly identified protected-path, naming inconsistency, and stale branch. No false positives on code quality. Human reviewer did not catch anything the review agent missed.
  • Code agent: Initial output was clean — a focused single-line change matching the issue specification.
  • Fix agent: Correctly addressed the naming-consistency finding. The second fix (rebase) completed successfully from the agent's perspective — the failure was in post-script infrastructure, not agent judgment.
  • Root cause: The primary failure was the known post-script gitleaks bug (fix(ci): post-fix gitleaks scan false-positives when fix agent merges or rebases main #6259). The secondary cause was 16 days of branch staleness that made a simple rebase bring in 684 commits of main's history.

Notes

  • Issue #6030 remains open with ready-to-code. The current AGENTS.md (rewritten via PR fix(#6299): detect zero-test-file packages in coverage skill #6301) partially addresses the concern through a topic-specific guidance table entry about "adding or removing subcommands," but the specific bullet point about grepping for sibling commands when adding a new subcommand is still absent.
  • Total wasted compute: 1 code agent run, 3 review runs, 2 fix runs — all for a change that was never merged.

Proposals skipped (target repo not allowed)

File manually or update create_issues.allow_targets in config.yaml:

  • Fix agent should assess branch salvageability before attempting rebase on very stale branches (fullsend-ai/agents)

@github-actions
github-actions Bot deleted the agent/6030-agents-md-doc-guidance branch September 27, 2026 03:03

This branch was previously deployed

1 inactive deployment
dev — e77280fb Deployed Aug 26, 2026 by fullsend-ai-coder[bot] via behaviour #10701
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation ready-for-review Triggers review agent dispatch requires-manual-review Review requires human judgment risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AGENTS.md: add doc-update guidance for new CLI command additions

1 participant