Contribute

Overview

Produce clean, respectful, atomic contributions with lean context by grouping work products, delegating monotone edits to micro-agents, and writing small, cherry-pickable PRs.

This applies whenever you are contributing to ANY upstream repository you don't own outright — typically a fork that tracks someone else's origin/upstream remote (a specific example the author built this against was contributing back to a fork of OpenAI's Codex CLI, but the workflow is general).

Scope (MANDATORY)

When invoked, you MUST:

• Find which repo is upstream and what its own contribution norms are: check git remote -v for an upstream (or equivalently-named) remote, and look for a CONTRIBUTING.md at the repo root. If neither is present, ask the person which repo they're contributing to and whether it has a contribution guide, rather than guessing.
• Locate and follow that repo's own CONTRIBUTING.md if one exists.
• Decide if the change is a bug fix (usually eligible for a contribution back upstream) or a feature (often not eligible — check the target repo's own policy; many open-source projects only accept features via prior discussion/RFC).
• If eligible: prepare the contribution per that CONTRIBUTING.md.
• If not eligible, or if there is no clear path to send it upstream: follow the same professional atomic commit/branch flow, but commit/push ONLY to your own fork so the upstream maintainers can cherry-pick if they want (no PR opened against upstream).
• Until the person confirms which repo and which contribution norms apply, still follow the general discipline below (atomic grouping, one branch per product, respectful credit) using generic conventions.

Workflow

1) Define atomic work products

• List the exact files changed and group them by intent.
• Keep each group independently reviewable and reversible.
• Use references/atomic-work-products.md for grouping patterns and current examples.

2) Decide if micro-agents are needed

• Use micro-agents only for monotone, low-judgment edits.
• Create a separate prompt per agent; never append to a shared directions file.
• Use references/micro-agent-briefs.md to generate a strict, minimal brief.

3) Execute the edits

• Restrict file access to the scoped list.
• Use apply_patch for single-file edits.
• Stop after the edit and report only the result.

4) Split commits and branches

• One branch per atomic work product.
• One commit per atomic work product.
• Use references/branch-and-pr-template.md for exact commands and PR text format.

5) Document respect and ownership

• Keep OpenAI attribution intact.
• Phrase changes as extensions, not replacements.
• Include a short credit line in PR descriptions.

Lean context rules

• Open only the files needed for the current atomic change.
• Avoid repo-wide scans unless the task requires them.
• Keep instructions under 10 lines per micro-agent.
• Do not modify core prompts unless explicitly asked.

References

• references/atomic-work-products.md
• references/micro-agent-briefs.md
• references/branch-and-pr-template.md