Imported from ROCm/rocm-cli (
AGENTS.md). Install upstream withnpx skills add ROCm/rocm-cli. Copyright stays with the author.
name: rocm-cli-oss-contribution description: Safe, high-quality contribution workflow for upstream-facing work in rocm-cli. Activate before any upstream PR, issue, review reply, public fork push, or other external-facing GitHub action. allowed-tools: Bash(git:), Bash(gh:), Bash(cargo:), Bash(python:), Bash(make:*), Read, Grep, Glob, Edit, Write
AGENTS: Safe OSS Contribution Workflow For rocm-cli
Use this workflow for any upstream-facing work — PRs, issues, review replies, or public-fork branches — in this or any other public repository. This is a blocking requirement before upstream-facing activity.
0) Activation And Scope
Activate this workflow before any of these actions:
- opening or editing an upstream PR
- opening or editing an upstream issue
- posting or editing an upstream comment or review reply
- pushing a branch intended for upstream
This workflow adds OSS safety and verification guardrails on top of normal dev flow.
1) Core Operating Rules
- Solve the reported problem, not an adjacent symptom.
- Be explicit about what is verified versus assumed.
- Never silently skip verification; if a check cannot run, state it clearly.
- Surface options and tradeoffs when multiple approaches are valid.
- Require explicit user approval for high-blast-radius actions:
- force-pushes
- opening/closing/merging PRs
- public comments/review replies
- changes to shared or public state
2) Company Identity Required, Internal Content Forbidden
Identity requirements stay intact:
- use your employer's author/committer identity (when required)
- include DCO sign-off (
git commit -s) - keep commit signing enabled when configured; do not bypass with
--no-gpg-sign,-n, or--no-verify
Signing and sign-off are now enforced, not just policy: local prek hooks
check signing config on every commit (commit-signing-configured) and verify
the full range on push (verify-commits), and a blocking CI gate
(commit-signatures) re-checks every PR with GitHub "Verified" status. See
docs/commit-signatures.md.
Content restrictions for upstream surfaces:
- do not include internal/proprietary names, aliases, URLs, hostnames, gateways, cluster names, or registry paths
- do not include links to internal tracking systems or unrelated internal usernames
- bare Jira/EAI-style ticket IDs (e.g.
EAI-1234) are permitted anywhere this rule applies; do not flag them - apply this rule to PR titles/bodies, issue text, comments, review replies, commit messages, branch names, code comments, fixtures, and logs
Use neutral external framing (for example: "backend" or "gateway") rather than internal or vendor-specific ownership phrasing.
Leak scan before each upstream push/PR/comment batch:
INTERNAL_KEYWORDS_PATTERN='internal|confidential|proprietary|private|jira|confluence|\.corp|\.internal'
git diff <upstream-base>..HEAD \
| grep -inE "$INTERNAL_KEYWORDS_PATTERN" \
&& echo "REVIEW each hit" || echo "diff clean"
This default pattern is intentionally generic so the workflow runs as-is. Refine INTERNAL_KEYWORDS_PATTERN with your organization's internal names and systems. Also manually review non-diff text surfaces (PR body, comments, issue text, branch name).
3) Reproduce First, Then Fix The Actual Issue
- reproduce the reported issue before claiming root cause or fix
- verify that the same reproduction passes after the change
- test boundary paths (non-default config, larger inputs, alternate trigger paths)
- do not relabel an adjacent improvement as "the fix" if the original repro still fails
Every bug fix ships with a regression test in the same change:
- test fails before fix and passes after fix
- choose unit/integration/e2e level based on where the bug lives
- if an e2e cannot run in default CI, state the gap in PR text and cover at another CI level
User-observable behavior needs a scenario, not only a unit test. This applies to
features as well as fixes. If the change alters what a user of the CLI can observe —
command output, exit codes, files or paths the CLI creates, or which runtime/engine it
selects — then that behavior must be covered by a Gherkin scenario in
tests/e2e-cucumber/features/, adding or updating the scenario and its step
definitions when no existing scenario already covers it:
- a unit test asserting the internal helper does NOT discharge this; it proves the function, not the behavior
- if a scenario for the behavior already exists, say in the PR text which
@id:it is and that the change makes it pass — do not silently rely on it - if the scenario can only run on a gated lane (
@requires-gpu,@nightly), say so in the PR text and name the lane that will exercise it - purely internal changes (refactors, CI plumbing, docs) do not need one; say why in the PR text rather than leaving it unexplained
4) Live State Verification Before Any External Claim
Before each stateful decision or public status update:
- refresh remote state (
git fetch) - re-check PR status and checks with live
ghqueries - verify review context against current PR head commit
Do not rely on stale memory, partial CI views, or prior snapshots. Subagent reports are hypotheses until directly re-verified. When re-verifying, match the verification scope to the claim: if subagent claimed "tests pass", re-run the same test suite; if it claimed "no conflicts", do the rebase locally; if it claimed "leak-free", re-run the scan. A passing unit test asserting exact string content only proves the string is unchanged, not that the claim is true — re-derive the claim against the actual code path rather than accepting the test as proof.
After rebase/cherry-pick/merge, grep for conflict markers:
grep -rn "^<<<<<<<\|^=======\|^>>>>>>>" .
For leak scans, use upstream base origin/main (or upstream default branch if different):
INTERNAL_KEYWORDS_PATTERN='internal|confidential|proprietary|private|jira|confluence|\.corp|\.internal'
git diff origin/main..HEAD \
| grep -inE "$INTERNAL_KEYWORDS_PATTERN" \
&& echo "REVIEW each hit" || echo "diff clean"
Planning and scratch artifacts are not repository documentation. Keep plans/,
implementation logs, and agent working notes out of commits; durable design
documentation belongs under docs/.
5) Investigate rocm-cli Before Editing
Understand existing patterns first:
- contributor and behavior docs in
README.md,docs/, andskills/ - workspace topology from
Cargo.toml - sibling implementations in
apps/,crates/, andengines/ - existing tests and conventions in
docs/testing.md
Fix at the correct layer (root cause), not by shrinking symptom visibility. If approach choice is ambiguous, present alternatives and recommend one.
Keep docs and behavior claims in sync while editing:
- when a command's flags, defaults, arguments, or observable behavior change, update README.md, its --help/doc comment, docs/testing.md, and docs/manual-testing.md in the same change — do not leave user-facing docs for a follow-up
- the same behavior claim (e.g. "does X automatically") often repeats across README.md, --help doc comments, printed CLI output, and docs/*.md; each drifts independently, so grep for the claim's wording across all of them, not just the surface you're editing, and check each against the actual code path
6) rocm-cli Architecture Guardrails
Current workspace members:
- apps:
apps/rocm,apps/rocmd - shared crates:
crates/rocm-core,crates/rocm-engine-protocol - engine crates:
engines/lemonade,engines/vllm
Shared UI components — reuse rather than hand-rolling new ones:
apps/rocm/src/cli_progress.rs's Spinner for a caller-driven indicator that
only advances when the caller's own loop ticks it (e.g. serve's
HTTP-polling wait loop); that same file's AnimatedSpinner for progress that
must keep animating between caller updates, which can go quiet for long
stretches (e.g. a download or the ComfyUI/SDK extraction spinner); and
crates/rocm-dash-tui/src/ui/approval.rs for approval-state prompts.
Guardrails:
- new subsystems/subcommands: default their domain implementation to its own file from day one (full domain extraction, e.g.
therock.rs/comfyui.rs— privatemodinapps/rocm, accessed via qualified paths; the clap command enum and its dispatch function usually stay inmain.rs, though not always — seedocs/architecture.md'sbootstrap.rsnote), not growth insidemain.rs/lib.rsawaiting a future extraction pass; seedocs/architecture.mdfor the module map and the mechanical-relocation alternative used for dispatch-adjacent clusters crates/rocm-engine-protocolis a contract surface; verify all impacted engines after protocol changes- first-party crate-layering invariants (e.g.
rocmdmust never depend onrocm) are enforced bycargo xtask check-crate-edges(xtask/src/crate_edges.rs); a new first-party dependency edge failing that check means the edge needs review, not a bypass - preserve strict GPU-required behavior; do not introduce silent CPU fallback
- respect platform gates (for example, native Windows handling for vLLM)
- pin third-party GitHub Actions to a full commit SHA with a trailing
# vX.Y.Zcomment, never a moving tag (@v2,@main); a retagged or compromised action otherwise enters CI silently. Bump the SHA and comment together when upgrading - before hand-rolling CLI output (completion reports, progress/spinner indicators, confirmation/approval prompts), check for and reuse the existing shared components (e.g.
apps/rocm/src/cli_report.rs::ActionReport) instead of duplicating the pattern inline; extend the shared component if it doesn't yet cover the needed case - supported host platforms are Windows and Linux only (including WSL where documented)
- platforms outside Windows/Linux are unsupported; do not implement, debug, or "fix" unsupported-platform behavior
- if a test fails only on unsupported platforms (e.g., macOS), skip or mark as out of scope; do not alter logic to make it pass
- add a comment documenting why the test is skipped (e.g.,
#[cfg_attr(not(target_os = "linux"), ignore)])
7) Local Assistant And Tool-Use Policy Consistency
When changing assistant-adjacent behavior, keep consistency with:
docs/llm-tool-use.mdskills/rocm-cli-assistant/SKILL.md
Required consistency points:
- inspect state before proposing mutation
- mutating actions require approval flow
- avoid invented shell/package-manager commands in assistant behavior paths
- preserve built-in assistant constraints and no-CPU-fallback policy
8) Verification Matrix For This Repo
Minimum quality gate before upstream-ready status:
cargo test --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
python scripts/smoke_local.py
When relevant to touched behavior, also run targeted checks from docs/testing.md, such as:
- focused Rust test groups for touched modules
- engine-specific GPU self-tests (
--self-test) or live GPU tests when hardware is available - release gate checks for release-path changes (
python scripts/single_exe_release_gate.py)
Execution environment expectations:
- By default, tests run on the developer's local machine (Linux or Windows, GPU optional but recommended for engine tests)
- GPU tests must pass on hardware if available locally; otherwise, they are expected to fail gracefully with clear messaging
- CI gates run on dedicated hardware and may have different results than local runs; use CI as the authoritative verification
- If a required check cannot run locally (e.g., GPU not available), say exactly what was not run and why in PR description
9) Release Trust And Signing Requirements
For release-affecting changes, follow docs/release-trust.md. In brief:
- checksum sidecars are required
- detached signatures are required when release policy mandates them
- do not bypass required signature modes
- preserve metadata/index signature verification behavior when enabled
Production signing and trust roots are owner-controlled inputs; do not substitute ad hoc keys as production trust anchors.
See docs/release-trust.md for the full policy, key management, and signing workflows.
10) Vendored Upstream Trees
If a vendored upstream tree is introduced in the future, apply the following rules:
- keep vendored changes minimal and attributable
- do not assume root workspace checks cover vendored workspace behavior
- follow sync notes in the appropriate upstream-sync documentation for pin updates and rebuild workflow
11) PR/Issue/Review Conduct
- keep each PR scoped to one logical change
- write for maintainers unfamiliar with local context
- avoid AI-generated boilerplate footers
- do not resolve reviewer threads you did not author; reply with fix commit context
- if reviewed code must be updated, explain what changed since review
- automated reviewers (e.g. Copilot) can post new findings on a commit that itself fixed earlier findings; after pushing a fix and replying to the original threads, re-fetch PR comments once more before treating the review round as closed
- to check whether a review comment already has a reply, do not call
gh api repos/OWNER/REPO/pulls/comments/$id/replies(GET); it 404s. Fetch the full list (gh api repos/OWNER/REPO/pulls/{pr}/comments --paginate) and cross-reference each comment'sin_reply_to_idagainst other comments'ids
Stacked and dependent PRs:
- Keep stacked PRs in draft until dependencies merge upstream (i.e., this repo's main branch, not just local)
- After dependencies merge, rebase and move PR out of draft
- Use
git rebase -ifor meaningful commit messages; prefer individual commits over squash unless the PR is a single logical unit - In PR body, clearly link to dependencies (e.g., "Depends on #123") and reference the target branch
12) CI Ownership: Drive To Green
Do not stop at opening/updating a PR. Watch checks to completion and drive to all-green.
- inspect failing logs directly
- fix real regressions from your change
- handle infrastructure flakes by rerun or maintainer escalation with evidence
- ensure flakes are not hiding real code failures in other checks
A red check means "not ready" until resolved.
13) Upstream Pre-flight Checklist
Run this checklist before any upstream push, PR update, issue update, or public reply:
- Live state refreshed (
git fetch, fresh PR/check status query) — §4 - Project conventions re-checked for touched area — §5
- Issue reproduced; fix validated against same repro plus boundaries — §3
- Regression test added and passing at the appropriate level — §3
- User-observable behavior covered by a scenario (or its absence justified) — §3
- Required local gates run (or explicitly documented gaps) — §8
- Leak scan completed across diff and non-diff text surfaces — §2
- Employer identity (if required), DCO sign-off, and commit-signing requirements preserved — §2
- Scope remains one logical change at correct layer — §11
- CI watched to completion and driven to green — §12
- User approval obtained for any high-blast-radius external action — §1
14) Related Internal Workflows
Use existing internal mechanics/workflows for implementation details such as commit, push, rebase, PR operations, and review-and-fix/dev-cycle automation where available.
15) Enforcement And Feedback
This workflow is advisory and human-enforced. Violations are addressed through:
- Pre-push review: Activate this workflow before pushing; review each step
- Code review: Upstream maintainers may request alignment if issues are found
- CI gates: Section 8 checks block CI; ensure all pass before opening PR
- Incident response: If a leak or policy violation reaches upstream, document the root cause and adjust workflow
This file defines OSS safety, verification, and publication guardrails for rocm-cli.