Change Proposals

Change proposals are one of two ways to update your playbook. Unlike direct updates, change proposals require team review before changes are applied.

Change Proposals require CLI version 0.23.0 or later. Run packmind-cli --version to check your version, and see CLI Installation to upgrade.

What are Change Proposals?

Change Proposals enable users to propose modifications to distributed artifacts (standards, commands, skills) directly from their local environment. Once submitted, proposals are reviewed and approved through the Packmind UI, ensuring that changes go through a controlled review process before being applied.

There are two ways to submit change proposals:

1. Use the packmind-update-playbook skill — the skill analyzes your coding session, identifies relevant changes, and submits proposals on your behalf automatically. This is the recommended approach.
2. Edit local files manually and use the CLI — modify distributed artifact files directly, then use packmind-cli playbook commands to stage and submit your changes.

Submitting Changes with the packmind-update-playbook Skill

The packmind-update-playbook skill automates the entire process. It analyzes your coding session, identifies what changed, and submits change proposals on your behalf.

It follows a four-phase workflow:

1. Summarize the session — extracts what was built, what patterns emerged, and what decisions were made.
2. Analyze existing artifacts — evaluates your current standards, commands, and skills against the session context.
3. Propose a change report — presents a numbered list of proposed updates, new artifacts, or deprecations for you to approve.
4. Apply approved changes — edits local files and submits proposals for review on Packmind.

The skill activates automatically when you use phrases like “update the playbook”, “sync standards”, or “check if we need new standards”. It can also be triggered after coding sessions where new patterns or conventions emerged.

Learn more about how skills work in the Skills Management section.

Submitting Changes with the CLI

The CLI requires a git repository with a remote configured. If no git repository or remote is detected, the command will fail with an error. Make sure you also have the CLI installed and configured — see CLI setup for details.

Local changes must be made on files deployed by Packmind during distribution — these include files in the .packmind/ directory as well as agent-specific directories such as .claude/, .github/, .cursor/, and others depending on your enabled AI agents (see Distribute artifacts for the full list).

Typical workflow

The playbook command uses a git-like staging workflow. You stage changes individually, then submit them all at once:

1. Edit local artifact files (standards, commands, or skills)
2. Run packmind-cli playbook diff to preview what changed
3. Run packmind-cli playbook status to see staged and untracked changes
4. Run packmind-cli playbook add <path> to stage the changes you want to submit
5. Run packmind-cli playbook submit -m "message" to submit staged changes as proposals

View local changes

To see what local changes differ from the published versions:

packmind-cli playbook diff

To include changes that have already been submitted:

packmind-cli playbook diff --include-submitted

To limit the analysis to a specific path:

packmind-cli playbook diff -p .claude/rules/

Check playbook status

To see which changes are staged for submission and which are untracked:

packmind-cli playbook status

Example output:

Changes to be submitted:
  - Standard "Error Handling" (updated)
    .claude/rules/error-handling.md

Changes not tracked:
  - Command "Deploy" (modified)
    .claude/commands/deploy.md

Use `packmind playbook add <path>` to track them

Stage changes

To stage a local artifact change for submission:

packmind-cli playbook add <path>

This stages the artifact but does not submit it. Packmind automatically detects whether the change is a creation or an update by comparing with the deployed version.

The file must be located in a recognized artifact directory:

Artifact type	Recognized directories
Commands	.claude/commands/, .cursor/commands/, .github/prompts/, .continue/prompts/, .packmind/commands/
Standards	.claude/rules/, .cursor/rules/, .github/instructions/, .continue/rules/, .packmind/standards/
Skills	.claude/skills/, .cursor/skills/, .github/skills/

File format requirements

• Commands: File must not be empty. Frontmatter with name: is optional.
• Standards: Must contain a heading and at least one rule (bullet point).
• Skills: Path must point to a directory containing a SKILL.md with valid frontmatter (name, description) and a non-empty body.

When it won’t work

The command will fail if:

• The file is not inside a recognized artifact directory
• The path points to a directory instead of a file (for commands and standards)
• The file content is invalid (empty command, standard without rules, skill missing SKILL.md)

Stage removal

To stage an artifact for removal from packages:

packmind-cli playbook rm <path>

The artifact must have been distributed by Packmind. The command will fail if the artifact was not deployed by Packmind (error: “This does not come from Packmind”).

After submitting with playbook submit, the removal proposal appears in the Review changes UI. The reviewer can either dismiss the proposal or choose Remove from packages. When removing, a dialog lets the reviewer select which packages to remove the artifact from, showing which packages are affected before applying the change.

Conflicts with removal proposals

If someone submits a modification and someone else submits a removal for the same artifact, both proposals appear in the review UI. Accepted removal proposals block conflicting proposals on the same artifact.

Unstage changes

To remove a previously staged change without submitting it:

packmind-cli playbook unstage <path>

Submit staged changes

To submit all staged changes as proposals:

packmind-cli playbook submit -m "Clarify error handling rules for API endpoints"

The message has a maximum length of 1024 characters. If you omit the -m flag in interactive mode, an editor will open for you to write the message.

If you see an error like Failed to submit "": is outdated, please run packmind-cli install to update it, it means the local artifact version is stale. Run packmind-cli install to fetch the latest versions, reapply your changes, and submit again.

Important: Pending Changes and the Install Command

While changes are pending (not yet accepted), running packmind-cli install will overwrite your local modifications with the server version. This will erase any unstaged or unsubmitted changes.

Always submit your staged changes with packmind-cli playbook submit before running packmind-cli install to avoid losing your work.

Reviewing Change Proposals in the UI

Once changes have been submitted, they can be reviewed in the Packmind web interface:

1. Navigate to the Review changes module from the sidebar menu
2. Proposals are grouped by artifact (standard, command, or skill)
3. Each proposal shows the modification type and a diff view highlighting additions and removals
4. Review each proposal and choose to accept or dismiss it
5. Click Apply changes to create a new version of the artifact with the accepted changes

Editing a Proposal Before Accepting

Reviewers can edit a change proposal’s proposed value before accepting it. This is useful when a proposal is mostly correct but needs minor adjustments — for example, fixing a typo in a proposed name or refining the wording of a description.

To edit a proposal:

1. Click the edit button on the proposal card
2. Modify the proposed value in the input field
3. Click Save & Accept to accept the proposal with your edits, or Cancel to discard your changes

Editing is available for name, description, and prompt updates on standards, commands, and skills. Other proposal types (rule changes, skill file updates, removals, and creations) cannot be edited.

Once a proposal has been edited:

• An Edited badge appears on the proposal card
• The card shows both the original proposal (collapsed by default) and the edited version, so reviewers can compare the two
• A Reset to original button lets you discard the edit and revert to the original proposed value
• If you undo the acceptance (move the proposal back to “To review”), the edit is discarded

Editing a proposal may also trigger conflict recomputation — if the edited value introduces or resolves a conflict with another pending proposal, the conflict status is updated automatically.

Conflict Management

If a new version of an artifact is published while a change proposal is still pending, the proposal becomes outdated. Packmind detects this conflict automatically — the proposal will be marked as conflicting and cannot be applied as-is. The submitter needs to rebase their changes on the latest version and submit a new proposal.