Contribute Upstream

Push improvements from the current project back to the claude-code-toolkit template.

Requires: template-sync-tools MCP server registered and running.

Workflow

1. Load Manifest and Find Candidates

Call template_load_manifest(project_path=".", skill_version="not-a-skill") (this is not the sync-template skill, so it passes the bypass sentinel). If errors, stop.

Call template_compute_status(project_path=".").

Collect files where locally_modified is true. Skip PROJECT_CONTEXT.md (always project-specific).

If no candidates: "No locally modified template files. Nothing to contribute."

Present the list:

Locally modified template files:
1. .claude/agents/architect.md
2. CLAUDE.md
3. .claude/agents/code-reviewer.md

2. Diff and Classify Each Candidate

For each candidate file:

1. Call template_get_diff(project_path=".", file_path=F, diff_type="local_changes")
2. Show the diff to the user
3. Ask: Generalizable (benefits any project using this variant) or Project-specific (unique to this project)?

Do NOT auto-classify. Always confirm with the user.

3. Reverse Placeholders

For each file confirmed as generalizable:

1. Call template_reverse_placeholders(project_path=".", file_path=F)
2. Show the replacements_made list so the user can verify placeholders were restored correctly
3. Show the reversed_content (or a relevant excerpt) for confirmation
4. If the user spots issues, they can provide corrected content

4. Check Cross-Variant Propagation

For each confirmed file:

1. Call template_check_cross_variant(template_repo=..., variant=..., file_path=F)
2. If can_propagate is true (all variants have identical content): offer to propagate to all variants
3. If can_propagate is false (variants differ): only update the current variant and warn:

   "{file} differs across variants. Only updating {variant}. Check other variants manually."

5. Write to Template

For files being propagated to all variants:

Call template_propagate_to_variants(template_repo=..., file_path=F, content=<reversed_content>, target_variants=<JSON array>).

For files only updating current variant:

Call template_propagate_to_variants(template_repo=..., file_path=F, content=<reversed_content>, target_variants=["<current_variant>"]).

6. Update Manifest

For each contributed file:

Call template_apply_file(project_path=".", file_path=F, source="skip") to update the manifest entry (marks the file as back in sync with template).

Write the JSON array of all template_apply_file results to a scratchpad file with the Write tool, then call template_finalize_sync(project_path=".", applied_files_path=<json-path>), where <json-path> is that file.

7. Report

Contribution Report

Contributed to template ({variant}):
  - .claude/agents/code-reviewer.md (propagated to: all variants)
  - CLAUDE.md (updated: {variant} only)

Skipped (project-specific):
  - .claude/agents/architect.md

Changes written to {effective location}. Review and commit when ready.

{effective location} is the template_repo_note from the template_propagate_to_variants response when present (under the v4.5.1 fallback the writes went into the server's own checkout, not the declared templateRepo), otherwise templateRepo.

Rules

• NEVER write to the template repo without showing the diff first
• NEVER auto-classify — always confirm with the user whether a change is generalizable or project-specific
• ALWAYS show reversed content for confirmation before writing to template
• Do NOT commit in the template repo — write files only, let the user review and commit
• Do NOT modify PROJECT_CONTEXT.md in the template (always project-specific)
• All placeholder reversal is handled by the MCP tools — do NOT reverse placeholders manually