Skip to content

Add upstream contribution guardrails to mach6 #282

Description

@aebrer

Summary

mach6 currently assumes GitHub is an appropriate shared workspace for plans, reviews, assessments, and progress comments. That is useful for repositories the user owns or teams that have opted into mach6, but it can create maintainer-facing noise when the user is a guest contributor in an upstream project.

Add a contribution-context guardrail so mach6 distinguishes owned/team work from upstream/guest contributions, defaults to private/local artifacts for guest work, and asks before making public GitHub writes when ownership is unclear.

Current Behavior

mach6 skills are optimized around public GitHub comments as shared memory:

  • mach6-issue can create or assess issues directly in the target repository.
  • mach6-plan opens a draft PR and posts a full implementation plan.
  • mach6-push posts progress comments after commits.
  • mach6-review posts full multi-agent review output plus independent assessment comments.
  • mach6-publish assumes the user can drive merge/release flow.

This is correct for dreb-owned repositories, but risky for guest contributions. The noisiest case is mach6-review: full automated review/assessment comments on an upstream PR can look like process spam rather than useful maintainer communication.

Proposed Behavior

Introduce a shared mach6 preflight/contribution mode concept used by the relevant skills:

  • owned — user owns the repository or this is a repo where mach6 comments are expected.
  • team — shared team repository where mach6 workflow is acceptable.
  • upstream_guest — user is contributing to a project they do not control.
  • unknown — ownership/expectations are unclear.

For owned and team, preserve the existing low-friction mach6 workflow.

For unknown, ask a single gating question before public writes, such as: "Do you own this repo / is it okay for me to post mach6 process comments here?"

For upstream_guest, default to private/local work:

  • Keep plans, reviews, assessments, and progress notes local or on a private fork/PR.
  • Do not open public draft PRs, post public implementation plans, or dump automated review output unless explicitly requested.
  • Public comments should be concise, human-curated, and maintainer-facing.
  • mach6-review should treat upstream PRs as read-only by default; full review output belongs on a private PR or local notes.
  • mach6-publish should refuse or redirect merge/tag/release operations for repos the user does not control.

Acceptance Criteria

  • mach6 has a documented contribution mode/preflight model covering owned, team, upstream_guest, and unknown.
  • mach6-issue avoids creating noisy upstream issues/comments by default and uses concise human-facing issue text when public posting is appropriate.
  • mach6-plan does not open public draft PRs or post implementation-plan comments in upstream/guest repos without explicit confirmation.
  • mach6-push does not post mach6-progress comments to upstream/guest PRs by default.
  • mach6-review does not post full review/assessment comments to upstream/guest PRs by default; it keeps output private/local unless explicitly authorized.
  • mach6-publish blocks or redirects merge/tag/release operations for upstream/guest contexts.
  • Owned-repo workflows remain low-friction and do not require repeated confirmation prompts.
  • Documentation explains the distinction between mach6 as shared memory in owned repos and private-first workflow in upstream repos.
  • Tests or scripted fixtures cover mode detection/branching for the touched skills where practical.

Context

This comes from a real upstream contribution workflow in KOReader/crengine:

  • Initial AI-assisted public workflow created maintainer fatigue through visible plans/reviews/progress comments.
  • The contributor apologized, moved exploration/refinement private, and returned with a smaller manually tested PR.
  • The follow-up PR received much better maintainer engagement, including maintainer testing and product-design discussion.

Relevant public examples:

The lesson is not "avoid AI" or "disable mach6". The lesson is that upstream public repositories are not scratchpads. mach6 should preserve its efficient shared-memory workflow for owned repos while steering inexperienced contributors toward private forks/local notes for first-pass upstream exploration.

Technical Notes

Likely touched areas:

  • packages/coding-agent/skills/mach6-issue/SKILL.md
  • packages/coding-agent/skills/mach6-plan/SKILL.md
  • packages/coding-agent/skills/mach6-push/SKILL.md
  • packages/coding-agent/skills/mach6-review/SKILL.md
  • packages/coding-agent/skills/mach6-publish/SKILL.md
  • packages/coding-agent/docs/mach6.md
  • Root/package README references if mach6 behavior is described there

Implementation could be purely skill-instruction/docs at first, or could later grow into shared helper guidance if skills gain common preflight machinery.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1Important for workflow completenessenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions