contribute

name

contribute

description

Evolves a capability's SHIPPED SOURCE — for everyone, not one user. A small tweak lands directly; a change to what the capability owns or does re-runs a scoped version of the capability-build research/design/approval flow. Use for upstream bug reports and change requests about an existing capability ('the steward should also flag X' as a fix for all users), when capability-evolve routes a source-level ask or a promotion here ('promote this MOD line', 'this should be for everyone'), or when a contribution needs drafting for upstream. Not for personalizing one user's install — that's capability-evolve (the overlay) — and not for something new to build — that's capability-build.

capability-contribute

Boundary: this skill edits capability source — for everyone who uses the package. Whose package decides where that is: the user's own capabilities live in <home>/personal/capabilities/<id>/ (theirs — edit directly); upstream-shipped ones live in <home>/upstream/capabilities/<id>/ and are never silently edited — changes to them are contributions, drafted on a branch. Changing how an installed capability behaves for this user is {{skill: evolve}} — the overlay, not the source.

Hard invariant: you never open a PR, file an issue, +1, push, fork, or create a remote branch — for upstream or any repo the user doesn't own — without the user's explicit approval or request. You draft and offer; only the user sends. gh pr create / gh issue create confirm once more before firing.

Invariant: the size of the change decides the ceremony, not the size of the ask. Classify before acting — see reference/judgment.md.

Intakes

• A source fix ("the steward double-counts a slip") — classify Small/Major below.
• A promotion (routed from {{skill: evolve}} with a MOD statement, or "promote this"): extract the mechanism — the user's literal nuance text never ships. A missing knob becomes a {{mod: <key>}} slot at the site the nuance targets plus the matching ONBOARDING.md question plus a MOD.example.md placeholder (the three land together; ONBOARDING and MOD.example are presence-paired). Tell the user: their concrete answer stays in their MOD; once the upstream change lands in an upgrade, the MOD statement retires. Generality uncertain → the lightest rung is a signal issue, not a PR (the ledger search and issue-first path are in reference/contribute.md).

Classify

• Small — wording, a threshold, a personalization answer, a knob promotion; no new file beyond the knob's question/placeholder, no schema/contract change, doesn't change what the capability owns.
• Major — a new skill/agent/schedule/kb-zone, a schema or contract change, changes what the capability owns or is responsible for.

Judgment call — reference/judgment.md has worked examples to calibrate against, not a checklist to satisfy mechanically.

Then

• Small: apply where the feedback actually lives, and make it take effect now — a personalization answer changes through the {{skill: onboard}} skill (the only MOD.md writer), then the live render is synced to match (the §3.3 round-trip: overlay and install stay consistent, MOD.md stays the source of truth); a package-level tweak: whose package is it? The user's own (personal/capabilities/, built here or an importer draft) — edit it directly; it goes live on the next install/update. Upstream-shipped — draft the change on a branch and offer the contribution per reference/contribute.md (applying it locally only if the user accepts the divergence knowingly, as a MOD statement that retires when the PR lands). Either way: tell the user what changed and where — transparent, not silent, but no approval gate for their own package.
• Major: interrupt like {{skill: build}}'s detector does, then run the scaled-down procedure in reference/procedure.md.

Authority

• May freely: classify, apply a small change to the user's own packages (via onboarding for answers, personal/ edits for package tweaks), sync the live render a changed answer personalizes, draft branches/PR bodies/issues, tell the user what changed.
• Report-only: what changed and where, for small edits.
• Ask first: anything classified major (research/design/approval before it applies, same gate as a new capability's Build stage) — and every write that leaves the machine toward upstream: PRs, issues, +1s, pushes, forks, remote branches. No exceptions.