Vc:publish

vc-publish

Push harness improvements from the current development repo to the remote kit repository (vibecode-pro-max-kit). This is the maintainer counterpart to vc-update.

• vc-update = user pulls latest harness INTO their project FROM the remote
• vc-publish = maintainer pushes improvements FROM the development repo TO the remote kit repo

Prerequisites

• Local checkout of the kit repo (git clone git@github.com:withkynam/vibecode-pro-max-kit.git)
• .vc-publish-config file in the current repo root (see Configuration below)
• Git push access to the remote kit repo

Configuration

Create .vc-publish-config in the repo root:

{"kitRepoPath": "/path/to/vibecode-pro-max-kit"}

If this file is missing, ask the user for the kit repo checkout path and offer to create it.

Workflow

Step 1: Load Configuration

1. Read .vc-publish-config from the current repo root.
2. If missing, ask the user for the kit repo local checkout path.
3. Verify the path exists and contains vc-manifest.json.
4. Verify the kit repo worktree is clean (git -C <kitRepoPath> status --porcelain). If dirty, warn and ask whether to proceed or abort.

Step 2: Read Manifest

5. Read vc-manifest.json from the kit repo checkout.
6. Extract the current version.

Step 3: Resolve Both File Sets

7. Run the resolver against the kit repo to get the kit file list:

   node <kitRepoPath>/resolve-manifest.mjs --root <kitRepoPath> --json
   

   Extract files (kit managed files) and kitOnly (kit-exclusive files).

8. Run the resolver against the dev repo to get the dev file list:

   node <kitRepoPath>/resolve-manifest.mjs --root <devRepoRoot> --json
   

   Extract files (dev managed files).

   Note: The resolver uses the manifest from the --root directory. Since the dev repo has a copy of vc-manifest.json, the resolver works against it. If the dev repo doesn't have the resolver script, copy it from the kit repo first or use the kit repo's copy with --root pointing to the dev repo.

Step 4: Compute Diff

9. Compare the two resolved file sets:
   • Files in dev files but NOT in kit files: new (will be added to kit).
   • Files in kit files but NOT in dev files: removed (will be removed from kit).
   • Files in both: compare content via diff. Classify as modified or unchanged.
   • strip files (AGENTS.md, AGENTS.md): always flag for content review regardless of diff status.

Step 5: Print Diff Summary

10. Print a summary table:

vc-publish diff: current repo -> kit repo (v2.1.0)
================================================

FILES:
  [modified]  .Codex/agents/vc-execute-agent.md  (+8 -3)
  [modified]  .Codex/hooks/lib/scout-checker.cjs  (+2 -1)
  [new]       .Codex/skills/vc-new-skill/SKILL.md
  [strip]     AGENTS.md (needs content review)
  [strip]     AGENTS.md (needs content review)
  [unchanged] .Codex/settings.json
  ... (350 more unchanged)

Total changes: 4 files modified, 1 new, 0 removed

Step 6: STOP -- Confirm Publish

11. STOP and ask the user:
    • Confirm they want to publish these changes.
    • Specify version bump type: patch, minor, or major.
    • Or abort.

Version bump semantics:

• Patch (2.1.0 -> 2.1.1): hook fixes, skill doc updates, minor agent prompt tweaks
• Minor (2.1.0 -> 2.2.0): new skills, new agents, new development protocols
• Major (2.1.0 -> 3.0.0): AGENTS.md structure changes, manifest schema changes, breaking workflow changes

Step 7: Apply Changes

12. On confirm:
    • Copy all modified and new managed files from current repo to kit repo checkout.
    • For each removed file: delete it from the kit repo checkout.
    • AGENTS.md and AGENTS.md stripping: Do NOT copy the current repo's project-specific versions directly. Instead:
      1. Read the current repo's AGENTS.md/AGENTS.md.
      2. Read the kit repo's existing harness-only version as base.
      3. Apply only methodology/structural changes from the dev repo to the kit's harness-only version.
      4. Strip all project-specific content:
         • Technology stack details (frameworks, databases, versions)
         • Feature list / "Current features" entries
         • Project-specific context groups
         • Hardcoded package manager (replace with generic)
         • MCP server instructions (project-specific config)
         • Project-specific routing rules
         • Absolute paths (/Users/...)
         • Product name references ("Flowser", "flowser-turborepo")
      5. Verify the result is harness-only methodology with no project leaks.
    • Update vc-manifest.json: bump version field per the chosen bump type. No other manifest changes needed -- glob patterns are stable, new files are automatically included.
    • Create symlinks if missing (.agents/skills -> ../.Codex/skills).

Step 8: Leak Detection

13. Verify no project-specific content leaked into the kit repo:

# Must return empty -- any matches indicate leaked content
grep -ri "flowser\|tRPC\|Prisma\|Supabase\|CloakBrowser\|OpenClaw" AGENTS.md AGENTS.md

# Must return empty -- no absolute paths
grep -r "/Users/" .

14. If leak detection fails:
    • Print the offending lines.
    • Revert the changes in the kit repo (git -C <kitRepoPath> checkout .).
    • STOP and report the leak. Do NOT commit or push.

Step 9: Commit and Tag

15. In the kit repo:

cd <kitRepoPath>
git add -A
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z

Step 10: Push

16. Push to remote:

git push origin main && git push --tags

17. If push fails (e.g., rejected, auth error), report the error. The commit and tag are preserved locally for retry.

Step 11: Print Summary

18. Print publish summary:

vc-publish complete
===================
Version:       v2.2.0 (was v2.1.0)
Files changed: 4
Remote:        git@github.com:withkynam/vibecode-pro-max-kit.git
Tag:           v2.2.0

Key Changes from v1.0

• No manifest array maintenance. The glob patterns in include/exclude/kitOnly are stable. Adding a new skill or agent requires zero manifest edits. The only manifest change at publish time is the version bump.
• Resolver-driven diffing. Both repos are resolved through the same resolve-manifest.mjs script, ensuring consistent file sets.
• No managed/managedDirs arrays to update. The old workflow of adding new files to these arrays is eliminated.

Rules

• ALWAYS run the full resolver diff (Steps 3-4) even when changes already exist in the kit repo. Direct kit edits (README, translations, community files) do not replace the dev→kit diff. Both change sources must be captured in the same publish.
• NEVER copy project-specific files: process/context/all-context.md (with real content), process/features/*, process/general-plans/* (with real plans)
• ALWAYS verify no project-specific content leaked before committing (Step 8)
• ALWAYS show the diff summary before publishing (Step 5-6)
• AGENTS.md and AGENTS.md require special handling -- never copy the development repo's project-specific versions directly
• Kit repo checkout path is stored in .vc-publish-config (add to .gitignore)
• The only manifest edit at publish time is the version bump -- glob patterns are stable

Reference

See references/vc-publish.md for the detailed algorithm, AGENTS.md/AGENTS.md stripping rules, error handling, and example outputs.