---
name: pattern-pack
description: Install, list, or remove argo pattern packs (Agentforce, React, Platform Events, Change Data Capture, External Objects, Big Objects, Field Service, Industries, CMS, Data Cloud). Each pack adds domain-specific patterns, quality-checklist items, and optionally agents/skills to the project.
data-access: none
---

You are managing **pattern packs** for the project. Packs are self-contained modules under `${CLAUDE_PLUGIN_ROOT}/templates/packs/`; install adds them to the user's project, remove takes them out. Format is defined in `${CLAUDE_PLUGIN_ROOT}/docs/pack-format.md`.

## Read Project Config First

```bash
source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
PATTERNS_DOC="$(sf_config_get '.paths.patternsSalesforceDoc' "$ENV")"
PROJECT_DIR="${CLAUDE_PROJECT_DIR}"
INSTALL_LOG="${PROJECT_DIR}/.claude/argo-packs.json"
```

## Input

`$ARGUMENTS`:
- `list` — list available packs and their install status
- `add <pack-name>` — install a pack
- `remove <pack-name>` — remove a previously-installed pack
- `info <pack-name>` — print the pack's README, pattern list, checklist additions
- `--force` — overwrite existing pack installation

## Steps

### `list`

```bash
ls -1 "${CLAUDE_PLUGIN_ROOT}/templates/packs/" 2>/dev/null
# For each, read pack.json and INSTALL_LOG to determine status
```

Output a table:
```
| Pack | Display Name | Status | Version |
|------|--------------|--------|---------|
| platform-events | Platform Events | ✅ installed v1.0.0 | 1.0.0 |
| change-data-capture | Change Data Capture | not installed | 1.0.0 |
| big-objects | Big Objects | not installed | 1.0.0 |
| ...
```

### `info <pack-name>`

```bash
PACK="${CLAUDE_PLUGIN_ROOT}/templates/packs/$NAME"
[[ -d "$PACK" ]] || exit 2
cat "$PACK/README.md"
echo "---"
echo "Patterns:"
grep -E '^## ' "$PACK/patterns.md" | sed 's/^## //'
echo "---"
echo "Checklist additions:"
[[ -f "$PACK/checklist.md" ]] && cat "$PACK/checklist.md" || echo "(none)"
```

### `add <pack-name>`

1. Verify the pack exists: `${CLAUDE_PLUGIN_ROOT}/templates/packs/<name>/pack.json`
2. Read `pack.json`:
   ```bash
   PACK_JSON="${PACK}/pack.json"
   API_REQ=$(jq -r '.requires.sfApiVersion // empty' "$PACK_JSON")
   API_HAVE=$(sf_config_get '.platform.apiVersion' "$ENV")
   DEPRECATED=$(jq -r '.deprecated // false' "$PACK_JSON")
   SUPERSEDED_BY=$(jq -r '.supersededBy // empty' "$PACK_JSON")
   ```
3. **If the pack is deprecated**, refuse the install and print the migration command:
   ```
   [pattern-pack] '<name>' is deprecated and ships no patterns.
   [pattern-pack] Use '<supersededBy>' instead:
                    /argo:pattern-pack add <supersededBy>
   ```
   Exit code 1. (`remove <name>` still works on a deprecated pack — that's how a project pinned to the old name unsticks itself.)
4. Verify API version: numerically `API_HAVE >= API_REQ` (or warn if not)
5. Check INSTALL_LOG; if already installed and not `--force`, exit 1 with a message
5. Append `patterns.md` to the project's `${PATTERNS_DOC}` with header markers:
   ```markdown
   <!-- pack:<name>@<version> begin -->
   <!-- Generated by /argo:pattern-pack add <name> on <iso> -->
   ...patterns content...
   <!-- pack:<name> end -->
   ```
6. If `checklist.md` exists, append to `docs/quality-checklist.md` with the same markers
7. If the pack ships agents (`pack.json: installs.agents`), copy each to `.claude/agents/` (project-local — doesn't pollute the plugin)
8. If the pack ships skills (`pack.json: installs.skills`), copy each directory to `.claude/skills/`
9. Update `${INSTALL_LOG}` (create if needed):
   ```json
   {
     "installed": [
       {"name": "platform-events", "version": "1.0.0", "installedAt": "2026-04-28T16:00:00Z"}
     ]
   }
   ```
10. Print a summary of what was added

### `remove <pack-name>`

1. Locate the begin/end markers in the project's docs and remove the bracketed block
2. Delete project-local agents/skills shipped by the pack
3. Update `${INSTALL_LOG}` to remove the entry

## Output

Default after `add`:
```
[pattern-pack] Installed 'platform-events' v1.0.0

Added to docs/patterns/salesforce-patterns.md:
  - PE-1: Platform Event Publisher
  - PE-2: Apex Trigger Subscriber for Platform Events
  - PE-3: Platform Event Replay
  - PE-4: High-Volume Platform Event Patterns
  - PE-5: Platform Event Error Handling

Appended to docs/quality-checklist.md:
  - 4 new items under Apex/Async

Project-local agents installed: 0
Project-local skills installed: 0

Suggested next steps:
- Read the pattern descriptions in docs/patterns/salesforce-patterns.md
- Check the worked example in <CLAUDE_PLUGIN_ROOT>/templates/packs/platform-events/examples/
- Re-run /argo:code-review or @qa to factor the new patterns into reviews
```

CI mode: emit JSON `{"installed": "platform-events", "version": "1.0.0", "patternsAdded": 5, "checklistItemsAdded": 4}`.

## Exit codes
- 0 — operation succeeded
- 1 — already installed (without `--force`), or remove on uninstalled pack
- 2 — pack not found, version requirement not met, install error

## Rules

- **Markers are sacred.** Never modify the bracketed install section by hand; future `remove` depends on the markers being intact
- **Don't auto-update.** When a newer pack version ships, the user must `remove` then `add` (or `add --force` to upgrade)
- **Project-local install for agents/skills.** Pack-shipped agents/skills go to `.claude/agents/` and `.claude/skills/` in the user's project — **not** in the plugin's namespace. They're invoked the same way (`@agent-name` / `/skill-name`), but they're project-specific
- **Verify api-version.** A pack that needs API 60.0 won't work in a project pinned at 58.0
- **`info` mode never modifies anything.** It's for previewing before `add`

## Available packs

(See `/argo:pattern-pack list` for the live inventory.)