Upstream Contribute

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

2. Apply locally as override (immediate benefit)

Create an override so the project benefits immediately:

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

With frontmatter:

---
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:

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

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)

./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), run the Stage-4 gate before opening the PR:

./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:

# 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