Upstream Contribute

---
model_tier: inherit
name: upstream-contribute
description: "Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package."
domain: process
scope:
  write: []
  verification_reason: "execution.handler is internal, so this skill spawns no subprocess — writes happen through the agent's declared allowed_tools. No command can prove a scope the skill never executes."
execution:
  type: assisted
  handler: internal
  allowed_tools: ["Bash(gh:*)"]
workspaces:
  - agent-config-maintainer
packs:
  - meta
---

# upstream-contribute

## When to use

- A new skill was created in a project that should be shared across all projects
- A rule or skill improvement was discovered that benefits all consumers
- A bug was found in a shared skill, rule, or command
- The `learning-to-rule-or-skill` skill identified something worth upstreaming
- An override was created locally and should become the new default
- A project-specific skill/rule could be **generalized** to benefit all consumers
- The `upstream-proposal` rule suggested a contribution and user agreed

Do NOT use when:

- **The user has NOT given explicit consent** — this is the #1 rule
- The content already exists in the shared package
- The learning is truly one-off and cannot be generalized

## Goal

Contribute a learning, skill, rule, or fix from a consumer project back to the
shared `agent-config` package — with correct file placement, quality gates, and PR structure.

## Core principles

- **⛔ Consent first** — NEVER create a PR, branch, or any upstream action without explicit user approval
- **Universality first** — the contribution must work for ALL consumers, not just one project
- **Generalize when possible** — project-specific content CAN become universal with adaptation
- **Evidence-based** — learnings must have occurred 2+ times or be clearly generalizable
- **Complete pairs** — both uncondensed and condensed versions required
- **Quality verified** — must pass linter before PR creation
- **Local benefit immediately** — use override for instant project benefit while PR is pending

## A repeated override is a signal, and a signal is not evidence

```
THE SAME ARTIFACT OVERRIDDEN IN INDEPENDENT INSTALLS IS THE CHEAPEST AVAILABLE
HINT THAT A SHIPPED DEFAULT IS WRONG. IT IS A HINT.
NEVER CHANGE A SHIPPED DEFAULT ON OVERRIDES FROM ONE ORGANISATION.
INDEPENDENT MEANS DIFFERENT TEAMS, NOT DIFFERENT DIRECTORIES.
```

`agent-config doctor --check override-set` reports which shipped artifacts a
tree overrides and in how many layers. Two same-culture installs overriding the
same artifact is **n=2 from one toolchain culture**, which is a discovery
channel and not a mandate — and the temptation to "just fix the default, we
already know" is exactly how a general package becomes one organisation's house
style.

**What makes an aggregate admissible**, matching the *Evidence-based* and
*Universality first* principles above:

- overrides from **independently operated** consumers, not several repositories
  of one team;
- the overriding change **converging on the same substance**, not merely
  touching the same filename — two teams deleting different halves of a rule
  are not agreeing about anything;
- a **named public mechanism** that explains why the shipped default is wrong,
  rather than "several people changed it".

Below that bar, the signal is one input to a future aggregate and nothing more.
Record it and leave the default alone.

**The signal carries no consumer content, by construction.** Artifact kind, name
and a layer count — the type has no field that can hold a path, a diff or
anything from the tree, so privacy is the schema's shape rather than a scrubbing
pass that could fail. Never widen it to make a proposal more persuasive; a
proposal that needs the consumer's diff is a proposal that has not cleared the
bar.

## Package repository

The shared agent-config package lives at:

```
git@github.com:event4u-app/agent-config.git
```

GitHub: `https://github.com/event4u-app/agent-config`

## Procedure

### 0. Mandatory consent gate

**This step is NON-NEGOTIABLE. No exceptions.**

Before ANY upstream work (branch, files, PR), ask the user:

```
> 🔄 This [skill/rule/guideline] could improve the shared agent-config package.
> [Brief explanation of what would be contributed and why it's valuable]
>
> 1. Yes — create an upstream PR
> 2. No — keep it project-local only
```

- **If user picks 2** → STOP. Do not mention upstream again for this item.
- **If user picks 1** → continue with the procedure below.
- **If `project.upstream_repo` is empty in `.agent-settings.yml`** → ask the user to configure it first.
- **NEVER skip this step**, even if the user previously agreed to other contributions.

### 1. Determine contribution type

| Type | Source path | Condensed path |
|---|---|---|
| **New skill** | `src/skills/{name}/SKILL.md` | `.augment/skills/{name}/SKILL.md` |
| **New rule** | `src/rules/{name}.md` | `.augment/rules/{name}.md` |
| **New command** | `src/domains/{domain}/{name}/command.md` | `.augment/commands/{name}.md` |
| **New guideline** | `docs/guidelines/{category}/{name}.md` | `.augment/guidelines/{category}/{name}.md` |
| **Update to existing** | Same path as original | Same path as original |

### 2. Apply locally as override (immediate benefit)

Create an override so the project benefits immediately:

```
agents/overrides/{type}/{name}.md
```

With frontmatter:

```yaml
---
overrides: {type}/{name}
mode: replace  # or extend
---
```

This step is optional if the change is low-urgency.

### 2b. Generalize project-specific content (if needed)

If the content is project-specific but could be made universal:

1. **Identify project-specific parts** — domain names, local paths, project conventions
2. **Abstract them** — replace with generic patterns, configurable values, or examples
3. **Show the user the diff** — original vs. generalized version
4. **Get approval** — user must confirm the generalized version is correct

Example: A project-specific "import-csv" skill → generic "file-import" skill with configurable format.

### 3. Prepare the upstream contribution

The agent needs access to the package repository. Ask the user:

```
> The improvement should go to the shared agent-config package.
> I need to create a PR in `event4u-app/agent-config`.
>
> 1. I have the package repo cloned locally — tell me the path
> 2. Clone it for me into a temp directory
> 3. I'll handle the PR manually — just give me the files
```

**Option 1:** User provides path → work directly in that repo.

**Option 2:** Clone into temp directory:

```bash
git clone git@github.com:event4u-app/agent-config.git /tmp/agent-config-upstream
cd /tmp/agent-config-upstream
```

**Option 3:** Output the file contents as copyable blocks for the user.

### 4. Create branch and files

```bash
cd {package-repo-path}
git checkout main && git pull
git checkout -b feat/skills/{name}  # or fix/rules/{name}, etc.
```

Create both files:

- **Source version** → `src/{type}/{name}` (full, verbose, human-readable)
- **Condensed version** → `.augment/{type}/{name}` (token-efficient, preserving all code blocks,
  headings, frontmatter, validation, gotchas)

For skills, the condensed version should be 40-60% shorter than uncondensed.
For rules and commands, they are usually copied 1:1 (no condensation).

### 5. Ensure file quality

The files must:

- Have correct YAML frontmatter (`name`, `description`, `source: package`)
- NOT contain project-specific references (no domain names, local paths, FQDNs)
- Follow the skill/rule/command template structure
- Have exactly one trailing newline

### 6. Run quality gates (if working in the package repo)

```bash
./scripts-run src/scripts/skill_linter --all          # 0 FAIL required
./scripts-run src/scripts/check_condensation            # No errors for this file
./scripts-run src/scripts/condense --generate-tools    # Regenerate symlinks
bash scripts/condense.sh --check                # dist/agent-src/ in sync with source
```

If not in the package repo, note that these checks will run in CI after the PR is created.

### 6b. Proposal gate — MANDATORY when a proposal doc exists

If the contribution originates from a proposal under `agents/proposals/`
(produced by `learning-to-rule-or-skill` via the pipeline in
[`self-improvement-pipeline`](../../../docs/guidelines/agent-infra/self-improvement-pipeline.md)),
run the Stage-4 gate before opening the PR:

```bash
./agent-config proposal:check agents/proposals/{slug}.md
```

**Hard refusal rule:** if `./agent-config proposal:check` exits non-zero, STOP —
do not create the branch, do not push, do not open the PR. Surface the
findings to the user, ask them to fix the proposal (add evidence,
remove TODO markers, complete required sections), then rerun.

When no proposal doc exists (small fix, typo, pure bug-fix), skip this
step and document the rationale in the PR body under the Promotion
Gate.

### 7. Commit and create PR

Branch naming: `feat/skills/{name}`, `fix/rules/{name}`, `feat/commands/{name}`

Commit message format:

```
feat(skills): add {name} skill
fix(rules): improve {name} rule — {what changed}
feat(commands): add {name} command
```

PR title: Same as commit message.

PR body must use the package's PR template with these gates:

- **Promotion Gate** — learning occurred 2+ times, improves correctness, prevents real failure
- **Quality Gate** — linter passes, tests pass
- **Universality Gate** — no project-specific assumptions, benefits all consumers
- **Completeness Gate** — both versions present, symlinks regenerated

### 8. After merge — clean up override

Once the PR is merged and the package is updated in the project:

```bash
# In the consumer project
rm agents/overrides/{type}/{name}.md
composer update event4u/agent-config  # or npm update
```

The shared version now replaces the local override.

## Output format

1. Summary of what is being contributed (type, name, why)
2. File contents for both uncondensed and condensed versions
3. If working in the package repo: branch name, commit message, PR title
4. If Option 3: copyable file blocks for the user to paste
5. Reminder to clean up local override after upstream merge

## Gotcha

- Agent in consumer project doesn't know the package repo URL — this skill provides it
- Agent may try to edit `.augment/` in the consumer project — that's read-only (symlinked)
- Agent may forget the condensed version — both are mandatory
- Agent may include project-specific references in the skill — must be universal
- The `source` field in frontmatter must be `package`, not `project`
- Agent may not have git access to the package repo — Option 3 handles this gracefully

## Do NOT

- **Do NOT create any upstream artifact without explicit user consent** — this is the #1 rule
- **Do NOT open a PR if `./agent-config proposal:check` blocks** — fix the proposal first (step 6b)
- Do NOT edit `.augment/` in the consumer project — it's managed by the package
- Do NOT submit project-specific content without generalizing it first
- Do NOT skip the condensed version — both files are mandatory
- Do NOT forget to clean up the local override after upstream merge
- Do NOT bypass quality gates — they exist for a reason
- Do NOT assume consent from a previous contribution — ask every time