Tooling: auto-apply Universal Code pins to AGENTS.md / prompt instruction files

[monkeykinghq]

Summary

Add a small tool that auto-applies Universal Code adoption pins to project prompt and agent-instruction files — so adopting the Code is a one-command (or one-click) step instead of hand-editing every repo.

Motivation: we just walked a full multi-repo workspace and prepended the pin line to every AGENTS.md (and CLAUDE.md where present). That should be productized.

Problem

Manual adoption does not scale:

• Many instruction entrypoints (AGENTS.md, CLAUDE.md, .cursorrules, system-prompt snippets, embed copies)
• Easy to miss a repo or leave an old version string after a Code upgrade
• Inconsistent wording / links across projects

Proposal

Ship an adoption / apply tool (name TBD, e.g. uc-apply or universal-code apply) that:

Must do

1. Locate common agent/prompt instruction files in a target path (cwd or --path), including at least:

   • AGENTS.md / agents.md
   • CLAUDE.md / Claude.md
   • Optionally: .cursorrules, GEMINI.md, .github/copilot-instructions.md, etc.

2. Pin (or update) a standard header line at the top of each file:

   This project follows the Universal Code vX.Y.Z — read https://github.com/monkeyking-hq/universal-code/blob/main/UC-EMBED-vX.Y.Z.md

3. Idempotent: if the pin is already present for the requested version, no-op; if an older version pin exists, upgrade the version + link.

4. Create AGENTS.md with only the pin when no instruction file exists (opt-in or default with --create-agents).

5. Dry-run mode (--dry-run) listing planned edits before writing.

6. Pin a specific version (--version 1.0.0) defaulting to latest stable published embed in this repo.

Should do

7. Workspace mode: walk multiple sibling git repos (--workspace / multi-path).
8. Optional embed inject: copy or reference compact embed text into a system-prompt file.
9. Report a clear summary: created / updated / skipped / failed.

Out of scope (for v1 of the tool)

• Changing the Code principles themselves
• Enforcing runtime behavior of models
• Auto-opening PRs across orgs (nice later)

Example UX

# single project
uc-apply --version 1.0.0

# whole workspace
uc-apply --workspace ~/workspaces/mkd-workspace --version 1.0.0 --dry-run
uc-apply --workspace ~/workspaces/mkd-workspace --version 1.0.0

Acceptance ideas

• Documented in README under “How to Use It → Examples”
• Safe on files with SPDX / front matter (pin stays first line)
• Version bump path works (v1.0.0 → later patch/minor)
• Works on Windows, macOS, Linux
• No network required if version + URL are explicit flags

Notes

This is a tooling / DX proposal, not a change to the Supreme Principle or Foundational Principles. Implementation language (shell, PowerShell, Go, Node, etc.) open for discussion.

Related: README examples for AGENTS.md pin + system-prompt binding (already landed on main).