docs(agents): sync module guidance files by EffortlessSteven · Pull Request #159 · EffortlessMetrics/shipper

EffortlessSteven · 2026-04-21T15:40:05Z

Summary

sync the local module-level �gents.md content into the canonical in-repo AGENTS.md files
keep the existing folder layout on main and update the guidance content in place
exclude tool-local and generated junk from the port

Notes

main already has the module AGENTS.md paths; this PR is the content port for the local files, not a new coverage-layout pass

Testing

not run (docs-only changes)

coderabbitai · 2026-04-21T15:40:22Z

Warning

Rate limit exceeded

@EffortlessSteven has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 47 minutes and 4 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 47 minutes and 4 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: d1ac99c3-208d-4160-a964-98b8b6d412b1

📥 Commits

Reviewing files that changed from the base of the PR and between eb0edf0 and 2ababc3.

📒 Files selected for processing (3)

AGENTS.md
crates/shipper-core/src/engine/parallel/AGENTS.md
crates/shipper/AGENTS.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/module-agents-port

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.}

gemini-code-assist

Code Review

This pull request updates the AGENTS.md guidance files across the workspace to align with recent architectural changes and provide better context for AI tools. However, several critical issues were identified: the introduction of hardcoded absolute Windows paths for workspace roots and documentation links breaks portability for other developers and CI environments. Additionally, the feedback highlights inaccuracies in entry point definitions for shipper-cli, inconsistent terminology regarding crate names in internal layers, and contradictory documentation about the existence of AGENTS.md files.

gemini-code-assist · 2026-04-21T15:41:47Z

 - Crate: shipper-cargo-failure
 - Path: crates/shipper-cargo-failure
- Workspace root: repository root for the current checkout; use repo-relative paths from this file
+- Workspace root: h:\Code\Rust\shipper


The workspace root is hardcoded to a local Windows path (h:\Code\Rust\shipper). This makes the documentation non-portable and will break for other users or in CI environments. It should remain generic, as it was previously.

Suggested change

- Workspace root: h:\Code\Rust\shipper

- Workspace root: repository root for the current checkout; use repo-relative paths from this file

gemini-code-assist · 2026-04-21T15:41:47Z

 - Prefer using existing fixtures and helpers rather than introducing inline test data.

-For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).
+For full workspace guidance, see [../../CLAUDE.md](H:\Code\Rust\shipper\CLAUDE.md).


The link to CLAUDE.md uses an absolute local Windows path. This will break for other users. Please use a relative path instead.

Suggested change

For full workspace guidance, see [../../CLAUDE.md](H:\Code\Rust\shipper\CLAUDE.md).

For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).

gemini-code-assist · 2026-04-21T15:41:47Z

- Workspace root: repository root for the current checkout; use repo-relative paths from this file
- Primary entry: src/lib.rs (`run()`); `src/main.rs` is the thin binary shim
+- Workspace root: h:\Code\Rust\shipper
+- Primary entry: src/main.rs


In shipper-cli, the core logic resides in src/lib.rs (via the run() function), while src/main.rs is just a thin binary shim. For an AI agent, src/lib.rs is the more relevant primary entry point for understanding behavior.

Suggested change

- Primary entry: src/main.rs

- Primary entry: src/lib.rs (run()); src/main.rs is the thin binary shim

gemini-code-assist · 2026-04-21T15:41:47Z

 # Layer: `ops` (I/O primitives)

-**Position in the architecture:** Layer 1 (bottom). The lowest layer of the `shipper-core` crate.
+**Position in the architecture:** Layer 1 (bottom). The lowest layer of the `shipper` crate.


The documentation refers to the shipper crate, but this file is located within shipper-core. According to the project structure, shipper-core is the engine crate where these layers reside. Using the specific crate name is more accurate for agent guidance.

Suggested change

**Position in the architecture:** Layer 1 (bottom). The lowest layer of the `shipper` crate.

**Position in the architecture:** Layer 1 (bottom). The lowest layer of the shipper-core crate.

gemini-code-assist · 2026-04-21T15:41:47Z

- Default visibility: `pub(crate)`. Only items truly part of `shipper-core`'s public API get `pub`.
- Each subfolder has its own local guidance files (`CLAUDE.md` and matching `AGENTS.md`) describing its single responsibility.
+- Default visibility: `pub(crate)`. Only items truly part of `shipper`'s public API get `pub`.
+- Each subfolder has its own `CLAUDE.md` describing its single responsibility.


The removal of AGENTS.md from this description is inconsistent with the fact that AGENTS.md files are being maintained and updated in the subfolders (e.g., ops/auth/AGENTS.md) within this same pull request.

Suggested change

- Each subfolder has its own `CLAUDE.md` describing its single responsibility.

- Each subfolder has its own local guidance files (CLAUDE.md and matching AGENTS.md) describing its single responsibility.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7f6b474266

ℹ️ 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".

chatgpt-codex-connector · 2026-04-21T15:42:50Z

 - Path: crates/shipper-cli
- Workspace root: repository root for the current checkout; use repo-relative paths from this file
- Primary entry: src/lib.rs (`run()`); `src/main.rs` is the thin binary shim
+- Workspace root: h:\Code\Rust\shipper


Keep AGENTS paths repo-relative and portable

This hard-codes a machine-specific Windows path (h:\Code\Rust\shipper) into guidance that is consumed in Linux/CI and other developer environments, so path-based instructions now point outside the checkout. The same substitution appears across many crate-level AGENTS.md files (including their CLAUDE.md links), which makes navigation and command context unreliable for anyone not on that exact host layout.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-21T15:42:50Z

+Re-exported at `shipper::cargo` (preserved backward compatibility with the old
+`shipper-cargo` public surface).


Remove nonexistent shipper::cargo re-export claim

This says callers should use shipper::cargo, but crates/shipper/src/lib.rs only re-exports config, engine, plan, state, store, and types; there is no cargo module on the shipper facade. Following this guidance causes unresolved-import failures and misdirects contributors about the public API surface.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-21T15:42:50Z

- Workspace root: repository root for the current checkout; use repo-relative paths from this file
- Primary entry: src/lib.rs (`run()`); `src/main.rs` is the thin binary shim
+- Workspace root: h:\Code\Rust\shipper
+- Primary entry: src/main.rs


Point shipper-cli primary entry to src/lib.rs

Marking src/main.rs as the primary entry is inaccurate: that file is just a thin wrapper, while pub fn run() and the real CLI behavior live in src/lib.rs. This misroutes future changes to the shim instead of the actual command implementation and test-covered logic.

Useful? React with 👍 / 👎.

codecov · 2026-04-21T16:11:48Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

docs(agents): sync module guidance files

7f6b474

gemini-code-assist Bot reviewed Apr 21, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Apr 21, 2026

View reviewed changes

docs(agents): fix synced guidance accuracy

2ababc3

EffortlessSteven merged commit 72270fd into main Apr 21, 2026
19 checks passed

	- Workspace root: h:\Code\Rust\shipper
	- Workspace root: repository root for the current checkout; use repo-relative paths from this file

	For full workspace guidance, see [../../CLAUDE.md](H:\Code\Rust\shipper\CLAUDE.md).
	For full workspace guidance, see [../../CLAUDE.md](../../CLAUDE.md).

	- Primary entry: src/main.rs
	- Primary entry: src/lib.rs (run()); src/main.rs is the thin binary shim

	Position in the architecture: Layer 1 (bottom). The lowest layer of the `shipper` crate.
	Position in the architecture: Layer 1 (bottom). The lowest layer of the shipper-core crate.

	- Each subfolder has its own `CLAUDE.md` describing its single responsibility.
	- Each subfolder has its own local guidance files (CLAUDE.md and matching AGENTS.md) describing its single responsibility.

		Re-exported at `shipper::cargo` (preserved backward compatibility with the old
		`shipper-cargo` public surface).

Uh oh!

Conversation

EffortlessSteven commented Apr 21, 2026

Summary

Notes

Testing

Uh oh!

coderabbitai Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Apr 21, 2026

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coderabbitai Bot commented Apr 21, 2026 •

edited

Loading