// Contribute framework improvements back to the upstream Manifest repo via PR. Use when the user says "contribute back", "open a PR upstream", "send this fix upstream", or wants to share a framework improvement.
| name | manifest-contribute |
| description | Contribute framework improvements back to the upstream Manifest repo via PR. Use when the user says "contribute back", "open a PR upstream", "send this fix upstream", or wants to share a framework improvement. |
Contribute improvements from your application back to the upstream Manifest repository.
When to use: The user says "contribute back", "open a PR upstream", "send this fix upstream", or similar.
The reverse of manifest-update. Update pulls from upstream into your app. Contribute pushes from your app back to upstream. Only framework-level changes are contributed — app-specific code stays local.
The manifest branch is your local read-only copy of the upstream framework. Contributions branch off manifest, cherry-pick framework commits from main, and open a PR against manifest-upstream.
manifest/ files).pi/skills/)extensions/)AGENTS.md framework sections, SPARK.md)features/)schemas/)services/)VISION.md — this is your app's identityconfig/)Verify the two-branch model is in place:
# Check manifest-upstream remote
git remote get-url manifest-upstream 2>/dev/null || echo "MISSING"
# Check manifest branch exists
git branch --list manifest | grep -q manifest || echo "MISSING"
If either is missing, set them up first (see the manifest-update skill).
Find commits on main (or the current feature branch) that touch framework files:
git log main --not manifest -- manifest/ .pi/skills/ extensions/ AGENTS.md SPARK.md --oneline
Read the full commit messages for context:
git log main --not manifest -- manifest/ .pi/skills/ extensions/ AGENTS.md SPARK.md --format="medium"
Present the list to the user. Ask which commits to contribute. Never auto-select everything.
Some commits may touch both framework and app-specific files. Identify them:
# For each candidate commit, check what files it touches
git show --stat <hash> --name-only
If a commit touches both framework and app files, warn the user: "This commit includes app-specific changes. I'll cherry-pick it and then strip the app-specific parts."
Make sure manifest is up to date before branching:
git fetch manifest-upstream
git checkout manifest
git merge --ff-only manifest-upstream/main
If fast-forward fails, warn the user — someone committed directly to manifest. This needs manual resolution before continuing.
git checkout manifest
git checkout -b contribute/<descriptive-name>
Use a descriptive name that reflects what's being contributed (e.g., contribute/router-path-validation, contribute/spark-web-dashboard).
git cherry-pick <hash1> <hash2> ...
For mixed commits (framework + app-specific changes):
git checkout manifest -- <app-specific-files>
git add -A
GIT_EDITOR=true git commit --amend
If a cherry-pick conflicts:
git add <resolved-file>
GIT_EDITOR=true git cherry-pick --continue
Always use GIT_EDITOR=true to avoid blocking on an interactive editor.
Run standard checks on the contribution branch:
bun test
bunx tsc --noEmit
Both must pass. Fix any issues before proceeding.
Determine whether you can push directly to the upstream repo or need to fork.
Check push access:
# Extract owner/repo from the manifest-upstream remote URL
UPSTREAM_URL=$(git remote get-url manifest-upstream)
UPSTREAM_REPO=$(echo "$UPSTREAM_URL" | sed -E 's#.+github\.com[:/]([^/]+/[^/.]+)(\.git)?$#\1#')
# Check if the authenticated user has push access
gh api "repos/$UPSTREAM_REPO" --jq '.permissions.push' 2>/dev/null
If you have push access (result is true) — push directly:
git push manifest-upstream contribute/<descriptive-name>
Then open the PR:
gh pr create \
--repo "$UPSTREAM_REPO" \
--base main \
--head contribute/<descriptive-name> \
--title "<type>(<scope>): <summary>" \
--body "<description>"
If you do NOT have push access (result is false or the check fails) — fork first:
# Fork the upstream repo (idempotent — no-ops if fork already exists)
gh repo fork "$UPSTREAM_REPO" --clone=false
# Get the authenticated user's GitHub username
GH_USER=$(gh api user --jq '.login')
# Add the fork as a remote (skip if already exists)
git remote get-url my-fork 2>/dev/null || git remote add my-fork "https://github.com/$GH_USER/$(basename $UPSTREAM_REPO).git"
# Push to the fork
git push my-fork contribute/<descriptive-name>
Then open the PR from the fork against the upstream repo:
gh pr create \
--repo "$UPSTREAM_REPO" \
--base main \
--head "$GH_USER:contribute/<descriptive-name>" \
--title "<type>(<scope>): <summary>" \
--body "<description>"
Note the --head "$GH_USER:contribute/..." syntax — GitHub needs the fork owner prefix when the PR comes from a fork.
PR guidelines (apply to both flows):
--base main targets the UPSTREAM repo's main branch (the framework). This is NOT your local main branch (your app). On GitHub, main = the framework. Locally, main = your app and manifest = the framework mirror.The PR title should follow conventional commit format. The body should:
manifest-commit skill conventions for knowledge-transfer writinggit checkout main # or your feature branch
The contribution branch stays around until the PR is merged or closed. Don't delete it prematurely.
bun test, bunx tsc --noEmit.GIT_EDITOR=true when git commands might open an editor.manifest branch directly. Contribution branches are created from it, but it remains a read-only mirror.Write knowledge-transfer git commits for Manifest projects. Use when making git commits. Commits include a typed subject line and a detailed body explaining what changed, why, and how.
Work with Manifest's frontend system — building, serving, dev workflow, debugging, and presets. Use when creating pages, components, debugging frontend errors, or configuring the build.
Structured implementation flow for Manifest features — from investigation through execution with subagents. Follows the full chain: investigate → clarify → explore → validate → plan → todos → branch → execute → review. No shortcuts. Invoke manually when building a new feature or significant change in a Manifest project.
Reflect on recent large changes and check if the rest of the codebase needs to catch up. Use after adding features, installing extensions, changing services, updating schemas, or making any significant structural change.
Resolve merge conflicts from upstream syncs or other merges. Preserves application identity while accepting framework and tooling improvements. Use when you see merge conflict markers or the user says "resolve conflicts", "fix merge", or "merge conflict".
Code review guidelines and quality rubric for Manifest projects. Covers framework conventions, feature structure, schema quality, and security. Shared by the reviewer subagent and available for manual reviews. Use when reviewing code changes.