contribute-turbo

Contribute Turbo

Submit staged turbo skill improvements from ~/.turbo/repo/ back to the upstream repo. The workflow adapts based on repoMode in ~/.turbo/config.json.

Step 1: Verify Contributor Status

Read ~/.turbo/config.json and check repoMode:

• "fork" or "source" — proceed
• "clone" — tell the user that contributions require a fork. Offer to help convert their clone to a fork (add their fork as origin, rename current origin to upstream). Stop.
• Missing config or repo — tell the user to run the Turbo setup first. Stop.

Verify the repo exists and has the expected remotes:

git -C ~/.turbo/repo remote -v

Step 2: Mirror Installed Skill Changes

Port session corrections from ~/.agents/skills/<name>/ (where edits land first) into ~/.turbo/repo/codex/skills/<name>/ (the basis for the contribution), leaving any persistent local customizations in the installed copy untouched.

Detect drifted skills:

for skill in ~/.agents/skills/*/; do
  name=$(basename "$skill")
  repo_dir=~/.turbo/repo/codex/skills/"$name"
  [ -d "$repo_dir" ] || continue
  diff -rq "$skill" "$repo_dir" >/dev/null 2>&1 && continue
  echo "$name"
done

For each drifted skill, first check whether the repo copy already has unstaged changes for it (git -C ~/.turbo/repo status --porcelain codex/skills/<name>/). If it does, use request_user_input to ask the user how to proceed before mirroring — those changes will conflate with mirrored corrections in Step 3 if not resolved.

Then read both versions of every changed file and classify each hunk:

• Correction — a session edit meant to improve the skill upstream. For modified files and new files, mirror the change into the repo copy with apply_patch. For files deleted from the installed copy, remove the repo copy with rm.
• Customization — a persistent local addition that does not belong upstream (extra workflow steps, personal paths, machine-specific notes, internal references). Leave it in the installed copy; do not propagate.
• Ambiguous — use request_user_input to confirm classification before applying.

Step 3: Check Cross-Edition Sync

Before staging, check whether the Codex paths drifted in Step 2 have parallel files in the Claude edition that should be updated alongside them:

• codex/skills/<name>/ ↔ claude/skills/<name>/
• codex/SKILL-CONVENTIONS.md ↔ claude/SKILL-CONVENTIONS.md
• codex/ADDITIONS.md ↔ claude/ADDITIONS.md
• codex/SETUP.md ↔ claude/SETUP.md
• codex/UPDATE.md ↔ claude/UPDATE.md
• codex/MIGRATION.md ↔ claude/MIGRATION.md

For each Codex path with pending changes, check whether the Claude sibling exists in ~/.turbo/repo/claude/ and whether the local repo already has matching changes for it (git -C ~/.turbo/repo status --porcelain claude/<path>). If a Claude sibling exists but has no matching changes, use request_user_input:

The change to codex/<path> touches the Codex edition, but claude/<path> exists and has no matching change. Does the Claude sibling need the same update?

Options:

• Yes, I need to update the Claude sibling — Stop. The user manually edits ~/.turbo/repo/claude/<path> (vocabulary differs; only behavioral parity is required) and re-runs this skill.
• No, this is Codex-specific — Continue.

If any sibling-update answer is "Yes", stop the workflow. Nothing has been staged yet, so there is no state to clean up before re-running.

Step 4: Review Pending Changes

Check what changes exist in the local repo:

git -C ~/.turbo/repo diff --name-only
git -C ~/.turbo/repo diff --cached --name-only

If there are unstaged changes to skill files, stage the specific skill directories that changed (both editions, when sibling updates landed in Step 3):

git -C ~/.turbo/repo add codex/skills/<name>/
git -C ~/.turbo/repo add claude/skills/<name>/   # if a sibling was updated

If there are no changes at all, tell the user there is nothing to contribute and stop.

Present the changes in a summary table:

| # | Skill | Change Summary |
|---|-------|----------------|
| 1 | $evaluate-findings | Added handling for security-default findings |
| 2 | $self-improve | Clarified routing for trusted reviewer feedback |

Use request_user_input to confirm which changes to include. If the user deselects some, unstage those files.

Step 5: Validate Skill Quality

Read ~/.turbo/repo/codex/SKILL-CONVENTIONS.md for the turbo project's skill conventions. These conventions supplement $create-skill's general best practices with turbo-specific patterns.

For each confirmed skill, if $create-skill has not been invoked for it in this session, run $create-skill to review and refine the skill. Any improvements from the review become part of the contribution.

Step 6: Craft Contribution Context

For each change, construct a "why" explanation. The goal: the turbo maintainer should understand what happened and why the existing instructions were insufficient, without learning anything about the contributor's project.

Use this template:

During [general workflow description], the skill's instructions [what was missing or wrong]. This caused [what happened]. The change [what it does] so that [benefit].

Example:

During a code review session, the evaluate-findings skill encountered a finding with security-default severity. The existing instructions only handled critical, high, medium, and low severities, causing the finding to be silently dropped. The change adds security-default to the severity handling table so these findings are properly triaged.

Privacy Filter

Before finalizing, verify each "why" description contains none of the following:

• Project or repo names
• File paths from the user's project
• Company or product names
• API keys, URLs, or credentials
• Business logic or domain-specific terminology that identifies the project
• User names beyond the contributor's GitHub handle

Output the drafted context as text. Then use request_user_input for approval. The user must approve the contribution message before proceeding.

Step 7: Commit Rules

Run $commit-rules to load commit message rules and technical constraints.

Step 8: Create Branch and Commit

When multiple skills were changed, batch related changes into a single branch and commit. Create separate branches only when changes are independent and unrelated.

Fork mode

Create a feature branch:

git -C ~/.turbo/repo checkout -b improve/<skill-name>-<short-desc>

Commit with a message matching the turbo repo style (check git -C ~/.turbo/repo log -n 10 --oneline). Incorporate the "why" context in the commit message.

Source mode

Stay on main. Commit directly with the same message style.

Step 9: Push

Fork mode

Run $github-voice to load writing style rules.

Push and create a PR:

git -C ~/.turbo/repo push -u origin improve/<skill-name>-<short-desc>

Create the PR against the upstream repo:

gh pr create --repo tobihagemann/turbo --head <user>:improve/<skill-name>-<short-desc> --title "..." --body "..."

PR body format:

## Summary
- [1-3 bullet points]

## Context
[The crafted "why" explanation from Step 6]

Return to main after creating the PR:

git -C ~/.turbo/repo checkout main

Report the PR URL.

Source mode

Pull and rebase before pushing to incorporate any upstream changes:

git -C ~/.turbo/repo pull --rebase origin main

If the rebase pulled in new commits, run $update-turbo to apply upstream changes (skill updates, migrations, config changes) to the local installation before pushing.

Then push:

git -C ~/.turbo/repo push origin main

Report the pushed commit hash.

Step 10: Update Config

In source mode, update ~/.turbo/config.json so the next $update-turbo does not re-surface the just-pushed changes:

1. Read ~/.turbo/config.json
2. Set `codex.las