Preface

In agent development or team collaboration, version management of deliverables often descends into chaos: files such as report_FINAL.xlsx, report_FINAL_v2.xlsx, and report_FINAL_really.xlsx sit in the same folder, and no one knows which one to trust. The root of this chaos lies in files being modified in place and ambiguous naming. Below, we introduce a plugin called deliverable-versioning that rebuilds delivery discipline through mechanical rules.

Plugin Overview

deliverable-versioning is a discipline tool for resolving delivery versioning chaos, maintained by ChenneyZhuang and released under the MIT License. It does not depend on external packages, and its core logic is implemented through a single SKILL.md file.

Core Features

The plugin enforces a set of mechanical rules to eliminate ambiguity about versions:

  1. Sent = Immutable
    Once a file has been sent, it must never be modified in place. New content must generate a new file, and the old file must remain in the state it was in when sent.

  2. Date-based naming, reject “final”
    Use dates and content for naming, and avoid ambiguous terms such as “final”. For example, proposal_2026-09-14.xlsx is more reliable than proposal_final_v3.xlsx.

  3. Single authoritative delivery directory
    Each project should maintain only one delivery directory as the single source of truth for “what was actually sent”.

  4. A ledger records file flow
    Maintain a ledger that records dates, file names, line counts, and recipients. The ledger can answer “what have we sent” without needing to dig through chat history.

  5. Check existence before creating a new version
    Before rebuilding a deliverable, first check whether the version already exists in the delivery directory. Rebuilding is a secondary source of truth, and checking existence first can avoid producing redundancies.

  6. Replacements must leave a trace
    When an older version is replaced by a newer one, the old file remains in the directory but must be marked in the ledger; references in documents should be updated.

Installation and Enabling

  1. Open a terminal and run the official installation command:
git clone https://github.com/ChenneyZhuang/deliverable-versioning ~/.claude/skills/deliverable-versioning
  1. After installation, the plugin version is v0.1.0 and requires no additional dependencies.

Typical Usage

When handling deliverable files, follow these steps:
* Avoid in-place modification: Do not modify a file that has already been sent; instead, create a new file.
* Use date-based naming: Name files using the filename_YYYY-MM-DD.extension format.
* Query history: By looking only at the delivery directory and the ledger, you can answer questions about sending history, recipients, and specific content.

Limitations and Notes

The effectiveness of this plugin depends heavily on execution discipline:
* Ledger discipline: Ledger recording depends on execution. Once a sending event is missed, the reconciliation logic fails.
* Legacy cleanup: For existing folders that are already chaotic, a one-time inventory must be performed first before the rules can take effect.

Summary

deliverable-versioning addresses delivery versioning chaos through immutable files and date-based naming. To use it, you must follow the rules above and ensure complete ledger records.

  • Plugin directory: https://www.skillhub.cn/plugins/ChenneyZhuang/deliverable-versioning
  • GitHub repository: https://github.com/ChenneyZhuang/deliverable-versioning