cc-os/plugins/cc-architect/workflows/plugin-config.md

# Workflow: Plugin Config

Single flexible workflow for all plugin configuration operations. Routes through a deterministic Ruby script, handles verification failures with self-healing, and presents results to the user.

## Who should do this work

| Phase | Model | Why |
|-------|-------|-----|
| Execute operation | Haiku | Mechanical: run script, parse JSON |
| Self-healing (if needed) | Sonnet | Diagnosis, workaround, friction logging |
| Interpret & report | Main | User-facing presentation |
| Cross-operation intelligence (if needed) | Sonnet | Chain audit -> fix -> verify |

## When to use

- Enable or disable a plugin in a project
- Register or unregister a plugin in the marketplace
- Debug plugin configuration issues
- List installed/registered plugins
- Audit plugin config state (marketplace, installed, settings)

## Inputs required

| Input | Required | Description |
|-------|----------|-------------|
| **operation** | Yes | `enable` \| `disable` \| `register` \| `unregister` \| `audit` \| `list` |
| **plugin_name** | Yes (except `list`) | Plugin name (kebab-case) |
| **marketplace_id** | For enable/disable/audit | Marketplace identifier (e.g. `cc-plugins`) |
| **project_path** | For enable/disable/audit | Absolute path to project using the plugin |
| **marketplace_file** | For register/unregister/audit | Path to `marketplace.json` |

## Script location

```
${CLAUDE_PLUGIN_ROOT}/scripts/plugin_config/plugin_config.rb
```

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success. JSON result on stdout. |
| 1 | Invalid operation or unexpected error. JSON diagnostic on stderr. |
| 2 | Schema mismatch. JSON diagnostic on stderr with `missing_keys`. |

---

## Phase 1: Execute Operation (Haiku)

**Purpose:** Run the Ruby script with the requested operation and parameters, parse the JSON output, and check for success.

**Steps:**

1. Build the command from inputs:
   ```bash
   ruby ${CLAUDE_PLUGIN_ROOT}/scripts/plugin_config/plugin_config.rb <operation> \
     --plugin=<plugin_name> \
     --marketplace=<marketplace_id> \
     --project=<project_path> \
     --marketplace_file=<marketplace_file>
   ```
   Omit parameters that are not applicable to the operation.

2. Execute the command and capture stdout, stderr, and exit code.

3. **If exit code = 0:**
   - Parse stdout as JSON.
   - Check for a `verified` field in the result. If `verified: false`, proceed to Phase 1b.
   - If `verified: true` or no `verified` field, proceed to Phase 2.

4. **If exit code = 1:**
   - Parse stderr as JSON diagnostic.
   - Report the error in Phase 2. Do not retry.

5. **If exit code = 2:**
   - Parse stderr as JSON diagnostic (schema mismatch with `missing_keys`).
   - Proceed to Phase 1b (self-healing).

---

## Phase 1b: Self-Healing Mode (Sonnet)

**Purpose:** Triggered on verification failure (`verified: false`) or schema mismatch (exit code 2). Diagnose root cause, attempt workaround, log friction.

**Triggers:**
- Exit code 2 (schema mismatch -- file exists but missing expected keys)
- Successful operation but `verified: false` (file was written but verification failed)

**Steps:**

1. **Diagnose:** Read the diagnostic JSON. Identify:
   - Which file failed (settings, marketplace, installed_plugins)
   - What was expected vs. actual
   - Whether the file exists, is valid JSON, and has the expected structure

2. **Attempt workaround:**
   - **Schema mismatch (missing keys):** Read the file, add missing keys with safe defaults (empty objects/arrays), write it back, then re-run the original operation.
   - **Verification failure:** Read the target file, compare with expected content, attempt a direct write if the content is close but not matching, then re-run.

3. **Assess severity:**
   - **Low:** Workaround succeeded on retry. Note in friction log, continue to Phase 2.
   - **Medium:** Workaround partially succeeded. Report to user with details, continue to Phase 2.
   - **High:** Workaround failed. Report blocker to user, do not proceed to Phase 2.

4. **Log friction:** Append an entry to `.claude/plugin-data/cc-architect/cli-friction-log.md`:
   ```markdown
   ### <date> -- <operation> -- <severity>
   **File:** <path>
   **Expected:** <what was expected>
   **Actual:** <what happened>
   **Workaround:** <what was tried>
   **Outcome:** <resolved | partially resolved | unresolved>
   ```

---

## Phase 2: Interpret & Report (Main)

**Purpose:** Present the operation result to the user in a clear, actionable format.

**Steps:**

1. Read the parsed JSON result from Phase 1.

2. Format based on operation type:

   **enable/disable:**
   - Confirm the action taken (plugin enabled/disabled in project).
   - Show the settings file path that was modified.
   - If `verified: true`, confirm success.

   **register/unregister:**
   - Confirm the plugin was added to/removed from marketplace.json.
   - Show the marketplace file path.

   **audit:**
   - Present each check (marketplace, installed, settings) with status.
   - List issues found with recommended fixes.
   - Summarize: "N checks passed, M issues found."

   **list:**
   - Display plugins in a table or list format.
   - Group by status if applicable.

3. If self-healing occurred (Phase 1b ran), include a note about what was auto-corrected.

---

## Phase 3: Cross-Operation Intelligence (Sonnet, conditional)

**Purpose:** When an audit reveals fixable issues, chain operations to resolve them automatically.

**Trigger:** Phase 2 completed an `audit` operation that found issues with available fixes.

**Steps:**

1. Review audit results for issues that have a `fix` field.

2. For each fixable issue, ask the user: "Would you like to fix these issues automatically?"

3. If user approves:
   - For each fix, determine the corresponding operation (e.g., "not registered" -> `register`, "not enabled" -> `enable`).
   - Execute each fix operation by re-entering Phase 1 with the appropriate parameters.
   - After all fixes, re-run `audit` to verify all issues are resolved.

4. Present final state to user.

---

## Error handling

| Scenario | Action |
|----------|--------|
| Ruby not installed | Report: "Ruby is required. Install with your package manager." |
| Script file not found | Report path and suggest checking cc-architect installation. |
| JSON parse failure on stdout | Treat as unexpected error. Log raw output to friction log. |
| Permission denied on config files | Report which file and suggest permission fix. |

## Anti-patterns

| Anti-Pattern | Why Wrong | Correct Approach |
|--------------|-----------|------------------|
| Editing config files directly | Bypasses verification | Always use the Ruby script |
| Retrying indefinitely on failure | Wastes tokens | Max 1 self-healing retry per operation |
| Running audit after every operation | Unnecessary overhead | Only chain audit when explicitly requested |
| Skipping Phase 1b on exit code 2 | Schema issues are recoverable | Always attempt self-healing for exit code 2 |