> ## Documentation Index
> Fetch the complete documentation index at: https://docs.packmind.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Change Proposals

<Info>
  **Enterprise Feature** — This functionality is only available in the
  **Enterprise** version of Packmind.
</Info>

Change proposals are one of two ways to update your playbook. Unlike [direct updates](/playbook-maintenance/updating-your-playbook#direct-updates), change proposals require team review before changes are applied.

<Note>
  Change Proposals require **CLI version 0.23.0 or later**. Run `packmind-cli   --version` to check your version, and see [CLI
  Installation](/tools/cli#installation) to upgrade.
</Note>

## 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.

<Info>
  Learn more about how skills work in the [Skills
  Management](/concepts/skills-management) section.
</Info>

## Submitting Changes with the CLI

<Note>
  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](/tools/cli) for details.
</Note>

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](/governance/distribution) 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:

```bash theme={null}
packmind-cli playbook diff
```

To include changes that have already been submitted:

```bash theme={null}
packmind-cli playbook diff --include-submitted
```

To limit the analysis to a specific path:

```bash theme={null}
packmind-cli playbook diff -p .claude/rules/
```

### Check playbook status

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

```bash theme={null}
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:

```bash theme={null}
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/`, `.gitlab/duo/skills/`, `.opencode/skills/`, `.agents/skills/` |

#### File format requirements

* **Commands**: File must not be empty. Frontmatter with `name:` is optional.

* **Standards**: Must start with a markdown heading (`# Name`) followed by content. Example:

  ```md theme={null}
  # My standard name

  Content goes here...
  ```

* **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:

```bash theme={null}
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 {type} 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:

```bash theme={null}
packmind-cli playbook unstage <path>
```

### Submit staged changes

To submit all staged changes as proposals:

```bash theme={null}
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.

#### Duplicate name detection

Before submitting, Packmind checks whether any artifact you are creating already exists in the target [space](/concepts/spaces) (by name, case-insensitive). If a duplicate is found, the submission is rejected with an error:

```
Error: A standard named "My Standard" already exists in this space.
Use "playbook unstage" to remove it or rename the artifact.
```

To resolve this, either rename your local artifact file or run `packmind-cli playbook unstage <path>` to remove it from the staged changes.

<Tip>
  If you see an error like **Failed to submit "{name}": {artifactType} 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.
</Tip>

## Important: Pending Changes and the Install Command

<Warning>
  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.
</Warning>

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

<Note>
  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.
</Note>

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.