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:

   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:

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