Skip to content

docs: add agents guidance coverage#157

Merged
EffortlessSteven merged 3 commits into
mainfrom
codex/pr-agent-docs
Apr 21, 2026
Merged

docs: add agents guidance coverage#157
EffortlessSteven merged 3 commits into
mainfrom
codex/pr-agent-docs

Conversation

@EffortlessSteven

Copy link
Copy Markdown
Member

Summary

  • add repo, crate, and module-level agents.md companions alongside existing CLAUDE.md guidance
  • add a crate local-doc coverage inventory and index it under repository maintenance docs
  • clean up stale/broken guidance wording in existing CLAUDE.md files so the new guidance surface is internally consistent

Verification

  • git diff --check
  • stale doc scan for absolute local links / this PR / future PR placeholders
  • CLAUDE.md to agents.md parity check (38 matching paths)

@gemini-code-assist gemini-code-assist 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.

Code Review

This pull request introduces a comprehensive set of agents.md files across the workspace to provide localized guidance for agentic coding tools. It also updates existing CLAUDE.md files to use relative paths and adds a maintenance inventory in docs/reference/crate-coverage.md. Feedback focuses on removing hardcoded local development paths from the new documentation files to ensure portability and addressing a documented 'invariant' in the git operations module that appears to codify an existing bug in error prefixing.

Comment thread crates/shipper-cargo-failure/agents.md Outdated

- Crate: shipper-cargo-failure
- Path: crates/shipper-cargo-failure
- Workspace root: h:\Code\Rust\shipper

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

This line contains a hardcoded local path (h:\Code\Rust\shipper) from your development environment. This should be generalized to a relative path or removed to ensure the documentation is portable and doesn't leak local system details. This same issue occurs in multiple other agents.md files added in this PR.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment thread crates/shipper-cli/agents.md Outdated

- Crate: shipper-cli
- Path: crates/shipper-cli
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment thread crates/shipper-config/agents.md Outdated

- Crate: shipper-config
- Path: crates/shipper-config
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment on lines +44 to +48
- **Error-text compatibility.** The outer `is_git_clean` wrapper prefixes the
underlying error with an extra `git status failed:` string; the CLI snapshot
tests assert against the doubled prefix (`git status failed: git status
failed: …`). Do not change this wording without updating
`crates/shipper-cli/tests/snapshots/e2e_expanded__preflight_*.snap`.

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

The documentation of a "doubled prefix" (git status failed: git status failed: …) as an invariant suggests a bug in the error handling logic. While documenting current behavior is helpful, calling it an "invariant" and warning against changing it codifies a bug. It would be better to fix the underlying logic and update the snapshots rather than treating this as a permanent design choice.

Comment thread crates/shipper-duration/agents.md Outdated

- Crate: shipper-duration
- Path: crates/shipper-duration
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment thread crates/shipper-registry/agents.md Outdated

- Crate: shipper-registry
- Path: crates/shipper-registry
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment thread crates/shipper-retry/agents.md Outdated

- Crate: shipper-retry
- Path: crates/shipper-retry
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment thread crates/shipper-sparse-index/agents.md Outdated

- Crate: shipper-sparse-index
- Path: crates/shipper-sparse-index
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment thread crates/shipper-types/agents.md Outdated

- Crate: shipper-types
- Path: crates/shipper-types
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

Comment thread crates/shipper-webhook/agents.md Outdated

- Crate: shipper-webhook
- Path: crates/shipper-webhook
- Workspace root: h:\Code\Rust\shipper

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

Hardcoded local path detected: h:\Code\Rust\shipper. Please generalize this to a relative path.

Suggested change
- Workspace root: h:\Code\Rust\shipper
- Workspace root: ../..

@coderabbitai

coderabbitai Bot commented Apr 21, 2026

Copy link
Copy Markdown

Warning

Rate limit exceeded

@EffortlessSteven has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 57 minutes and 36 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 57 minutes and 36 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e003604c-9f75-4410-923b-8b6616cdfb4b

📥 Commits

Reviewing files that changed from the base of the PR and between cd7cc4d and 9ead3ec.

📒 Files selected for processing (42)
  • AGENTS.md
  • crates/shipper-cargo-failure/AGENTS.md
  • crates/shipper-cli/AGENTS.md
  • crates/shipper-cli/src/output/AGENTS.md
  • crates/shipper-cli/src/output/progress/AGENTS.md
  • crates/shipper-config/AGENTS.md
  • crates/shipper-config/src/runtime/AGENTS.md
  • crates/shipper-core/AGENTS.md
  • crates/shipper-core/src/engine/AGENTS.md
  • crates/shipper-core/src/engine/parallel/AGENTS.md
  • crates/shipper-core/src/ops/AGENTS.md
  • crates/shipper-core/src/ops/CLAUDE.md
  • crates/shipper-core/src/ops/auth/AGENTS.md
  • crates/shipper-core/src/ops/cargo/AGENTS.md
  • crates/shipper-core/src/ops/git/AGENTS.md
  • crates/shipper-core/src/ops/lock/AGENTS.md
  • crates/shipper-core/src/ops/process/AGENTS.md
  • crates/shipper-core/src/ops/storage/AGENTS.md
  • crates/shipper-core/src/plan/AGENTS.md
  • crates/shipper-core/src/plan/chunking/AGENTS.md
  • crates/shipper-core/src/plan/levels/AGENTS.md
  • crates/shipper-core/src/runtime/AGENTS.md
  • crates/shipper-core/src/runtime/CLAUDE.md
  • crates/shipper-core/src/runtime/environment/AGENTS.md
  • crates/shipper-core/src/runtime/execution/AGENTS.md
  • crates/shipper-core/src/runtime/policy/AGENTS.md
  • crates/shipper-core/src/state/AGENTS.md
  • crates/shipper-core/src/state/events/AGENTS.md
  • crates/shipper-core/src/state/execution_state/AGENTS.md
  • crates/shipper-core/src/state/store/AGENTS.md
  • crates/shipper-duration/AGENTS.md
  • crates/shipper-encrypt/AGENTS.md
  • crates/shipper-output-sanitizer/AGENTS.md
  • crates/shipper-registry/AGENTS.md
  • crates/shipper-retry/AGENTS.md
  • crates/shipper-sparse-index/AGENTS.md
  • crates/shipper-types/AGENTS.md
  • crates/shipper-types/src/storage/AGENTS.md
  • crates/shipper-webhook/AGENTS.md
  • crates/shipper/AGENTS.md
  • docs/README.md
  • docs/reference/crate-coverage.md

Walkthrough

This pull request adds comprehensive documentation across the shipper workspace. It introduces a root-level agents.md providing orientation for agentic tools, adds crate-level and module-level agents.md guidance files throughout the codebase, corrects absolute filesystem paths to relative paths in existing CLAUDE.md files, and establishes documentation infrastructure for crate coverage tracking.

Changes

Cohort / File(s) Summary
Root & Workspace Guidance
agents.md, docs/README.md
New root-level guidance document for agentic tools with repository orientation and recommended workflows; updated docs README to include agents.md navigation link.
Crate Documentation Path Corrections
crates/shipper{-core,-cli,-config,-duration,-encrypt,-output-sanitizer,-registry,-retry,-sparse-index,-types,-webhook,-cargo-failure}/CLAUDE.md, crates/shipper/CLAUDE.md
Updated 14 crate-level CLAUDE.md files, converting absolute Windows filesystem paths to relative repository paths (../../CLAUDE.md).
Crate-level Agent Guidance
crates/shipper{-core,-cli,-config,-duration,-encrypt,-output-sanitizer,-registry,-retry,-sparse-index,-types,-webhook,-cargo-failure}/agents.md, crates/shipper/agents.md
Added new agents.md files to 14 first-party crates, each specifying scope, recommended cargo commands, and behavioral conventions for contributors.
shipper-core Architectural Documentation
crates/shipper-core/{CLAUDE.md,agents.md}, crates/shipper-core/src/{ops,plan,runtime,state,engine}/agents.md, crates/shipper-core/src/ops/{auth,cargo,git,lock,process,storage}/agents.md, crates/shipper-core/src/plan/{chunking,levels}/agents.md, crates/shipper-core/src/runtime/{environment,execution,policy}/agents.md, crates/shipper-core/src/state/{events,execution_state,store}/agents.md, crates/shipper-core/src/engine/parallel/agents.md
Documented all five architectural layers (ops, plan, runtime, state, engine) with layer-specific responsibilities, import constraints, and module layouts; documented sub-layer modules detailing public APIs, invariants, and expected file structures.
shipper-core ops & runtime Layer CLAUDE.md Updates
crates/shipper-core/src/ops/{CLAUDE.md,auth/CLAUDE.md,process/CLAUDE.md,storage/CLAUDE.md}, crates/shipper-core/src/runtime/{CLAUDE.md,execution/CLAUDE.md,policy/CLAUDE.md}, crates/shipper-core/src/plan/{CLAUDE.md,chunking/CLAUDE.md,levels/CLAUDE.md}, crates/shipper-core/src/state/CLAUDE.md
Updated existing CLAUDE.md files to reflect decrating effort history, adjust crate ownership references (e.g., shipper → shipper-core), clarify module responsibilities and boundaries, and update subfolder documentation conventions to include agents.md.
shipper-cli Output Module Documentation
crates/shipper-cli/src/output/agents.md, crates/shipper-cli/src/output/progress/agents.md
Documented output module scope and responsibilities for formatting CLI output; specified progress reporter API surface, behavioral invariants, and integration with prior shipper-progress crate.
Public API & shipper-types Documentation
crates/shipper-types/src/storage/{CLAUDE.md,agents.md}
Updated CLAUDE.md for storage module origin; added agents.md documenting StorageType enum, CloudStorageConfig, and related error types as pure data without I/O.
Documentation Infrastructure
docs/reference/crate-coverage.md
Added crate coverage tracking matrix documenting presence of README.md, CLAUDE.md, and agents.md for all first-party crates.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

  • Release v0.3.0-rc.1 #23: This PR documents the public APIs, modules, and invariants (e.g., chunk_by_max_concurrent, ProgressReporter, ops::cargo, state/store) that the referenced release PR modifies or adds functionality for.

Poem

🐰 Hop and document with glee,
Layer by layer, crate by crate, we see—
Guidance for agents, paths made true,
Architecture clear, from old to new! ✨
No code to hunt, just docs so bright—
The warehouse is mapped, all paths set right! 📚

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title 'docs: add agents guidance coverage' directly describes the main change: adding agents.md documentation files throughout the repository alongside existing CLAUDE.md guidance.
Description check ✅ Passed The description clearly relates to the changeset, explaining the addition of agents.md files at repo/crate/module levels, a coverage inventory, and cleanup of stale CLAUDE.md wording.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/pr-agent-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cd7cc4d740

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread AGENTS.md
@@ -0,0 +1,108 @@
# AGENTS.md

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Rename guidance files to AGENTS.md

This commit introduces guidance files as agents.md (lowercase) across the repo, but AGENTS-style discovery is typically case-sensitive on Linux and expects the exact filename AGENTS.md. In environments that follow that convention, none of these new files will be auto-loaded, so the new guidance coverage is effectively ignored. This directly undermines the purpose of the change and is reproducible anywhere filename matching is strict.

Useful? React with 👍 / 👎.

@coderabbitai coderabbitai 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.

Actionable comments posted: 19

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@crates/shipper-cargo-failure/agents.md`:
- Line 11: Remove the hardcoded "Workspace root: h:\Code\Rust\shipper" line from
the agents.md files (e.g., the line "Workspace root: h:\Code\Rust\shipper" in
crates/shipper-cargo-failure/agents.md) so those documents no longer contain
absolute Windows paths; simply delete that field from each affected agents.md
(the same removal applies to the other listed crates) since the workspace root
is documented via relative paths elsewhere.

In `@crates/shipper-cli/agents.md`:
- Line 11: Replace the machine-specific absolute Windows path
"h:\Code\Rust\shipper" in the file (and the same string in
crates/shipper-config/agents.md) with a portable alternative: either a relative
path (e.g., "./") or remove the workspace root line entirely; search for the
exact literal "h:\Code\Rust\shipper" to locate the entry in agents.md and update
or delete that line so the document is not tied to a local filesystem.

In `@crates/shipper-config/agents.md`:
- Line 11: Remove the machine-specific absolute Windows path from agents.md by
deleting or replacing the "Workspace root: h:\Code\Rust\shipper" line; either
change it to a relative path (e.g., "./" or "../" as appropriate) or omit the
workspace root line entirely so the document remains portable and free of local
links.

In `@crates/shipper-core/src/ops/CLAUDE.md`:
- Around line 37-39: Fix the inconsistent bullet indentation inside the "What
does NOT live here" section by making the "- Domain types — those live in
`shipper-types`." bullet match the other sibling bullets' indentation and
formatting; locate the "What does NOT live here" heading in CLAUDE.md and remove
or add the leading space so all three bullets (`shipper-registry`, `Domain
types`, `Orchestration`) use the same left alignment and dash spacing to satisfy
markdownlint MD005.

In `@crates/shipper-duration/agents.md`:
- Line 11: Replace the machine-local hard-coded path "Workspace root:
h:\Code\Rust\shipper" in crates/shipper-duration/agents.md with a portable
reference (e.g., "Workspace root: <repository-root>" or a relative path like
"../" or "${projectRoot}") so the document is usable by other contributors;
update the single line containing that exact string and ensure any follow-up
instructions in the file refer to this portable placeholder instead of an
absolute local drive path.

In `@crates/shipper-duration/CLAUDE.md`:
- Line 29: The file ends without a trailing newline; open the CLAUDE.md file and
append a single newline character at the end of the file so the final line "For
full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md)." is terminated
with one newline (ensure no extra blank lines are added).

In `@crates/shipper-encrypt/agents.md`:
- Line 11: Replace the hardcoded Windows path string "Workspace root:
h:\Code\Rust\shipper" with a portable relative reference; update the agents.md
entry to use a repository-root or relative path token (for example "./shipper"
or a workspace variable like "${workspaceRoot}/shipper") so the workspace root
is not tied to a specific OS/user. Ensure the new value replaces the exact text
"Workspace root: h:\Code\Rust\shipper" so the doc remains correct and portable.

In `@crates/shipper-output-sanitizer/agents.md`:
- Line 11: The hardcoded Windows path "Workspace root: h:\Code\Rust\shipper" is
not portable; replace that literal with a relative or environment-variable based
reference (e.g., "Workspace root: ./shipper" or use a placeholder like
"${workspaceFolder}/shipper") in agents.md so the workspace root is resolved
relative to the repository rather than a machine-specific absolute path.

In `@crates/shipper-output-sanitizer/CLAUDE.md`:
- Line 29: Add a single trailing newline at the end of the CLAUDE.md file so the
last line "For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md)."
is followed by one EOF newline to satisfy markdownlint rule MD047; simply edit
the file and insert one blank line after that final line.

In `@crates/shipper-registry/agents.md`:
- Line 11: Replace the hardcoded Windows path string "h:\Code\Rust\shipper"
under the "Workspace root:" entry in agents.md with a portable relative
reference (e.g., a relative path or remove the line entirely), since the "Path"
field already documents the repository layout; locate the "Workspace root:"
label and update or delete the hardcoded value so the file no longer contains
system-specific absolute paths.

In `@crates/shipper-registry/CLAUDE.md`:
- Line 29: The file CLAUDE.md is missing a trailing newline which triggers
markdownlint MD047; open CLAUDE.md and add exactly one newline character at the
end-of-file (immediately after the current Line 29) so the file ends with a
single blank line.

In `@crates/shipper-retry/agents.md`:
- Line 11: Replace the developer-specific absolute path "Workspace root:
h:\Code\Rust\shipper" in crates/shipper-retry/agents.md with a portable,
repo-relative description such as "Workspace root: <repository root>" or
"Workspace root: /path/to/repo" (or provide instructions to run from the
repository root), so the documentation no longer contains a local Windows path;
update the line that currently contains that exact string.

In `@crates/shipper-retry/CLAUDE.md`:
- Line 29: The file ends without the required single trailing newline; open the
CLAUDE.md in crates/shipper-retry and ensure the last line "For full workspace
guidance, see [../../CLAUDE.md](../../CLAUDE.md)." is followed by exactly one
newline character (remove any extra blank lines or missing newline at EOF so the
file ends with a single trailing newline to satisfy markdownlint MD047).

In `@crates/shipper-sparse-index/agents.md`:
- Line 11: The document currently embeds a machine-specific path string
"Workspace root: h:\Code\Rust\shipper"; replace that hardcoded path with a
neutral, portable placeholder (for example "Workspace root: <repository-root>"
or simply "Workspace root: repository root") so the guidance is
environment-agnostic and does not expose local filesystem details.

In `@crates/shipper-types/agents.md`:
- Line 11: The file contains a hardcoded Windows absolute path string "Workspace
root: h:\Code\Rust\shipper" which is not portable; replace that literal with a
relative or environment-agnostic reference (e.g., use a relative path like
"../.." or a placeholder such as "${workspaceRoot}" or simply "Workspace root:
<repo-root>") so the document no longer depends on a user-specific absolute
Windows path.

In `@crates/shipper-types/CLAUDE.md`:
- Line 29: The file CLAUDE.md is missing a single trailing newline at EOF; open
the file containing the line "For full workspace guidance, see
[../../CLAUDE.md](../../CLAUDE.md)." and append exactly one newline character
after that final line so the file ends with a single trailing newline (satisfies
MD047).

In `@crates/shipper-types/src/storage/agents.md`:
- Around line 11-16: Add blank lines before and after the markdown section
headings "## Public API" and "## Why this lives in shipper-types" in
crates/shipper-types/src/storage/agents.md so the headings are separated from
surrounding text; locate the headings by their exact text and ensure there is an
empty line above the "## Public API" line and one below it (and the same for "##
Why this lives in shipper-types") to satisfy markdown compliance.

In `@crates/shipper-webhook/agents.md`:
- Line 11: Replace the hardcoded Windows path found in the string "Workspace
root: h:\Code\Rust\shipper" with a portable relative or environment-based
reference (e.g., use a relative path like "./" or a variable such as
${workspaceRoot} or an explanatory placeholder) so the documentation/agents.md
is platform-agnostic and does not assume a specific user filesystem.

In `@crates/shipper-webhook/CLAUDE.md`:
- Line 29: The file CLAUDE.md is missing a trailing newline at EOF (MD047); open
CLAUDE.md and ensure there is exactly one newline character after the last line
("For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).") so the
file ends with a single newline and no extra blank lines.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ced2087c-06d2-47c6-80c8-0c6d2a0ff6ef

📥 Commits

Reviewing files that changed from the base of the PR and between 25e23ad and cd7cc4d.

📒 Files selected for processing (64)
  • agents.md
  • crates/shipper-cargo-failure/CLAUDE.md
  • crates/shipper-cargo-failure/agents.md
  • crates/shipper-cli/CLAUDE.md
  • crates/shipper-cli/agents.md
  • crates/shipper-cli/src/output/agents.md
  • crates/shipper-cli/src/output/progress/agents.md
  • crates/shipper-config/CLAUDE.md
  • crates/shipper-config/agents.md
  • crates/shipper-config/src/runtime/agents.md
  • crates/shipper-core/CLAUDE.md
  • crates/shipper-core/agents.md
  • crates/shipper-core/src/engine/agents.md
  • crates/shipper-core/src/engine/parallel/agents.md
  • crates/shipper-core/src/ops/CLAUDE.md
  • crates/shipper-core/src/ops/agents.md
  • crates/shipper-core/src/ops/auth/CLAUDE.md
  • crates/shipper-core/src/ops/auth/agents.md
  • crates/shipper-core/src/ops/cargo/agents.md
  • crates/shipper-core/src/ops/git/agents.md
  • crates/shipper-core/src/ops/lock/agents.md
  • crates/shipper-core/src/ops/process/CLAUDE.md
  • crates/shipper-core/src/ops/process/agents.md
  • crates/shipper-core/src/ops/storage/CLAUDE.md
  • crates/shipper-core/src/ops/storage/agents.md
  • crates/shipper-core/src/plan/agents.md
  • crates/shipper-core/src/plan/chunking/CLAUDE.md
  • crates/shipper-core/src/plan/chunking/agents.md
  • crates/shipper-core/src/plan/levels/CLAUDE.md
  • crates/shipper-core/src/plan/levels/agents.md
  • crates/shipper-core/src/runtime/CLAUDE.md
  • crates/shipper-core/src/runtime/agents.md
  • crates/shipper-core/src/runtime/environment/agents.md
  • crates/shipper-core/src/runtime/execution/CLAUDE.md
  • crates/shipper-core/src/runtime/execution/agents.md
  • crates/shipper-core/src/runtime/policy/CLAUDE.md
  • crates/shipper-core/src/runtime/policy/agents.md
  • crates/shipper-core/src/state/CLAUDE.md
  • crates/shipper-core/src/state/agents.md
  • crates/shipper-core/src/state/events/agents.md
  • crates/shipper-core/src/state/execution_state/agents.md
  • crates/shipper-core/src/state/store/agents.md
  • crates/shipper-duration/CLAUDE.md
  • crates/shipper-duration/agents.md
  • crates/shipper-encrypt/CLAUDE.md
  • crates/shipper-encrypt/agents.md
  • crates/shipper-output-sanitizer/CLAUDE.md
  • crates/shipper-output-sanitizer/agents.md
  • crates/shipper-registry/CLAUDE.md
  • crates/shipper-registry/agents.md
  • crates/shipper-retry/CLAUDE.md
  • crates/shipper-retry/agents.md
  • crates/shipper-sparse-index/CLAUDE.md
  • crates/shipper-sparse-index/agents.md
  • crates/shipper-types/CLAUDE.md
  • crates/shipper-types/agents.md
  • crates/shipper-types/src/storage/CLAUDE.md
  • crates/shipper-types/src/storage/agents.md
  • crates/shipper-webhook/CLAUDE.md
  • crates/shipper-webhook/agents.md
  • crates/shipper/CLAUDE.md
  • crates/shipper/agents.md
  • docs/README.md
  • docs/reference/crate-coverage.md

Comment thread crates/shipper-cargo-failure/agents.md Outdated

- Crate: shipper-cargo-failure
- Path: crates/shipper-cargo-failure
- Workspace root: h:\Code\Rust\shipper

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Search for absolute Windows paths in agents.md files

# Search for lines containing Windows drive letters followed by colon in agents.md files
rg -n '[A-Za-z]:\\' --glob '**/agents.md'

Repository: EffortlessMetrics/shipper

Length of output: 906


🏁 Script executed:

#!/bin/bash
# Check CLAUDE.md around line 29 to verify the claim about path removal
sed -n '20,40p' crates/shipper-config/CLAUDE.md

Repository: EffortlessMetrics/shipper

Length of output: 511


🏁 Script executed:

#!/bin/bash
# Also check the first few lines of agents.md files to understand structure
head -15 crates/shipper-cargo-failure/agents.md

Repository: EffortlessMetrics/shipper

Length of output: 421


🏁 Script executed:

#!/bin/bash
# Check root CLAUDE.md to see full context
head -40 CLAUDE.md

Repository: EffortlessMetrics/shipper

Length of output: 1906


Remove hardcoded Windows paths from all 11 agents.md files.

The agents.md file in shipper-cargo-failure (and 10 other crates) contains a hardcoded Windows path h:\Code\Rust\shipper at line 11. This contradicts the PR's cleanup of absolute local links, evident in root CLAUDE.md and shipper-config/CLAUDE.md which use relative references.

Remove the "Workspace root" field from all 11 affected agents.md files:

  • crates/shipper-cargo-failure/agents.md
  • crates/shipper-config/agents.md
  • crates/shipper-cli/agents.md
  • crates/shipper-duration/agents.md
  • crates/shipper-encrypt/agents.md
  • crates/shipper-registry/agents.md
  • crates/shipper-sparse-index/agents.md
  • crates/shipper-retry/agents.md
  • crates/shipper-webhook/agents.md
  • crates/shipper-output-sanitizer/agents.md

The workspace root can be inferred from the relative path structure and is already documented in the root CLAUDE.md.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@crates/shipper-cargo-failure/agents.md` at line 11, Remove the hardcoded
"Workspace root: h:\Code\Rust\shipper" line from the agents.md files (e.g., the
line "Workspace root: h:\Code\Rust\shipper" in
crates/shipper-cargo-failure/agents.md) so those documents no longer contain
absolute Windows paths; simply delete that field from each affected agents.md
(the same removal applies to the other listed crates) since the workspace root
is documented via relative paths elsewhere.

Comment thread crates/shipper-cli/agents.md Outdated
Comment thread crates/shipper-config/agents.md Outdated
Comment on lines +37 to 39
- `shipper-registry`, `shipper-webhook`, `shipper-sparse-index` — these are public crates that `shipper-core` depends on directly. No internal wrapper inside `ops/`.
- Domain types — those live in `shipper-types`.
- Orchestration — that's `engine/`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Fix list indentation consistency in the “What does NOT live here” section.

Line 37 is indented differently from sibling bullets, which triggers markdownlint (MD005).

Suggested fix
- - `shipper-registry`, `shipper-webhook`, `shipper-sparse-index` — these are public crates that `shipper-core` depends on directly. No internal wrapper inside `ops/`.
+- `shipper-registry`, `shipper-webhook`, `shipper-sparse-index` — these are public crates that `shipper-core` depends on directly. No internal wrapper inside `ops/`.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- `shipper-registry`, `shipper-webhook`, `shipper-sparse-index` — these are public crates that `shipper-core` depends on directly. No internal wrapper inside `ops/`.
- Domain types — those live in `shipper-types`.
- Orchestration — that's `engine/`.
- `shipper-registry`, `shipper-webhook`, `shipper-sparse-index` — these are public crates that `shipper-core` depends on directly. No internal wrapper inside `ops/`.
- Domain types — those live in `shipper-types`.
- Orchestration — that's `engine/`.
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 38-38: Inconsistent indentation for list items at the same level
Expected: 1; Actual: 0

(MD005, list-indent)


[warning] 39-39: Inconsistent indentation for list items at the same level
Expected: 1; Actual: 0

(MD005, list-indent)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@crates/shipper-core/src/ops/CLAUDE.md` around lines 37 - 39, Fix the
inconsistent bullet indentation inside the "What does NOT live here" section by
making the "- Domain types — those live in `shipper-types`." bullet match the
other sibling bullets' indentation and formatting; locate the "What does NOT
live here" heading in CLAUDE.md and remove or add the leading space so all three
bullets (`shipper-registry`, `Domain types`, `Orchestration`) use the same left
alignment and dash spacing to satisfy markdownlint MD005.

Comment thread crates/shipper-duration/agents.md Outdated
Comment thread crates/shipper-types/agents.md Outdated
- Prefer using existing fixtures and helpers rather than introducing inline test data.

For full workspace guidance, see [../../CLAUDE.md](H:\Code\Rust\shipper\CLAUDE.md). No newline at end of file
For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md). No newline at end of file

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Add a single trailing newline at EOF (MD047).

markdownlint-cli2 reports the file does not end with one newline; please append it after Line 29.

Proposed fix
 For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).
+
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).
For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 29-29: Files should end with a single newline character

(MD047, single-trailing-newline)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@crates/shipper-types/CLAUDE.md` at line 29, The file CLAUDE.md is missing a
single trailing newline at EOF; open the file containing the line "For full
workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md)." and append exactly
one newline character after that final line so the file ends with a single
trailing newline (satisfies MD047).

Comment on lines +11 to +16
## Public API
- `StorageType` — Enum: `File | S3 | Gcs | Azure`
- `CloudStorageConfig` — Configuration for any storage backend (bucket, region, base_path, credentials, etc.)
- `ParseStorageTypeError` — Error returned by `FromStr for StorageType`
- `ValidateStorageConfigError` — Error returned by `CloudStorageConfig::validate`

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🧹 Nitpick | 🔵 Trivial

Add blank lines around headings for markdown compliance.

The static analysis correctly identifies missing blank lines around the ## Public API and ## Why this lives in shipper-types headings.

📝 Suggested fix
 **Was:** Part of the standalone `shipper-storage` crate (split during the decrating effort).
 
 ## Public API
+
 - `StorageType` — Enum: `File | S3 | Gcs | Azure`
 - `CloudStorageConfig` — Configuration for any storage backend (bucket, region, base_path, credentials, etc.)
 - `ParseStorageTypeError` — Error returned by `FromStr for StorageType`
 - `ValidateStorageConfigError` — Error returned by `CloudStorageConfig::validate`
 
 ## Why this lives in shipper-types
+
 These are pure data — no I/O, no policy decisions. Embedders need to express "use this storage backend" through the stable contract crate. The runtime backend behavior lives in `shipper-core`'s internal storage layer and is unfinished (only filesystem is implemented today).

Also applies to: 17-20

🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 11-11: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@crates/shipper-types/src/storage/agents.md` around lines 11 - 16, Add blank
lines before and after the markdown section headings "## Public API" and "## Why
this lives in shipper-types" in crates/shipper-types/src/storage/agents.md so
the headings are separated from surrounding text; locate the headings by their
exact text and ensure there is an empty line above the "## Public API" line and
one below it (and the same for "## Why this lives in shipper-types") to satisfy
markdown compliance.

Comment thread crates/shipper-webhook/agents.md Outdated
- Prefer using existing fixtures and helpers rather than introducing inline test data.

For full workspace guidance, see [../../CLAUDE.md](H:\Code\Rust\shipper\CLAUDE.md). No newline at end of file
For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md). No newline at end of file

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Add the missing trailing newline at EOF.

markdownlint flagged MD047 for this file; please ensure there is exactly one newline after Line 29.

Proposed fix
 For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).
+
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).
For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 29-29: Files should end with a single newline character

(MD047, single-trailing-newline)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@crates/shipper-webhook/CLAUDE.md` at line 29, The file CLAUDE.md is missing a
trailing newline at EOF (MD047); open CLAUDE.md and ensure there is exactly one
newline character after the last line ("For full workspace guidance, see
[../../CLAUDE.md](../../CLAUDE.md).") so the file ends with a single newline and
no extra blank lines.

@codecov

codecov Bot commented Apr 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@EffortlessSteven EffortlessSteven merged commit 5a23167 into main Apr 21, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant