How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

forge-refresh - Prompt - OpenSmartRoute

Name: forge-refresh
Author: jpoutrin

Prompt file imported from jpoutrin/product-forge (.claude/commands/forge-refresh.md). Copyright stays with the author.

forge-refresh

Category: Plugin Management

Usage

/forge-refresh [options] [plugin-name]

Options

Option	Description
`--dry-run`	Preview actions without making changes
`--force`	Force reinstall even if all plugins are up to date
`--status`	Show current cache status only (no changes made)
`--verbose`	Show detailed issue descriptions for each plugin
`[plugin-name]`	Optional: Refresh only specific plugin (e.g., `product-design`)

Purpose

Validates Product Forge plugin cache state and refreshes outdated, corrupted, or invalid plugins. Use this command when:

Claude Code becomes unstable or unresponsive
Plugins don't appear or respond in Claude Code
Skills, commands, or agents are not recognized
After pulling updates to the source repository
When cache appears to be out of sync with source

How It Works

This command performs six phases of cache management:

Prerequisites - Verifies claude CLI, git, and jq are available
Detection - Scans plugin cache and compares with source repository
Reporting - Shows status of each plugin and any issues found
Backup - Creates timestamped backup of current installation state
Reinstallation - Clears stale cache and reinstalls plugins
Verification - Confirms installations succeeded and match source

What Gets Checked

For each plugin, the command validates:

SHA Match: Installed version matches source repository commit
Cache Exists: Plugin cache directory is present
Plugin Valid: Plugin structure passes validation checks

Status indicators:

✅ OK - Plugin is up to date and valid
⚠️ OUTDATED - Source has newer commits
❌ CORRUPTED - Cache directory missing
❌ INVALID - Plugin structure validation failed
⭕ MISSING - Plugin not installed at all

Execution Instructions for Claude Code

When this command is run, Claude Code should:

1. Parse the Arguments

Extract flags and plugin name from the command arguments:

--dry-run, --force, --status, --verbose are boolean flags
The last argument (if not a flag) is the optional plugin name

2. Delegate to Script

Run the refresh script with all provided arguments:

./scripts/refresh-plugins.sh "$@"

3. Interpret the Output

The script will display:

Status report with emoji indicators for each plugin
List of issues detected (if any)
Prompts for confirmation (unless --force or --dry-run)
Progress during installation
Final summary with results

4. Exit Codes

The script exits with:

0 - Success (all plugins refreshed successfully)
1 - Failure (some plugins failed to install, or prerequisites missing)
2 - (reserved for future use)

5. Display Results

Display all output from the script to the user. If there are failures:

Suggest checking the troubleshooting section in the output
Offer to run individual diagnostics like ./scripts/validate-all-plugins.sh
Recommend checking Claude Code logs if the issue persists

Examples

Check current cache status

/forge-refresh --status

Output shows status of all plugins without making any changes.

Preview what would be refreshed

/forge-refresh --dry-run

Shows exactly what actions would be taken, but makes no changes.

Refresh with detailed output

/forge-refresh --verbose

Shows status of all plugins with detailed issue descriptions.

Force refresh all plugins

/forge-refresh --force

Reinstalls all plugins regardless of current status. Use when you want a clean slate.

Refresh specific plugin only

/forge-refresh product-design

Only clears and reinstalls the product-design plugin, leaving others untouched.

Combine options

/forge-refresh --dry-run --verbose

Preview with detailed issue descriptions, no changes made.

Common Scenarios

Scenario 1: After pulling source updates

git pull
/forge-refresh

Refresh plugins after pulling new commits to match the updated source.

Scenario 2: Plugins not appearing in Claude

/forge-refresh --force

Force a complete reinstall if plugins became invisible or unresponsive.

Scenario 3: Check without making changes

/forge-refresh --dry-run

Preview what would be done before proceeding with actual refresh.

Scenario 4: Diagnose single plugin issue

/forge-refresh --verbose product-design

Check the status of a specific plugin with detailed diagnostic information.

Troubleshooting

If the command fails

The script will suggest troubleshooting steps in its output. Common next steps:

Verify plugins are valid:
```
./scripts/validate-all-plugins.sh
```
Check if source repo is up to date:
```
git pull
/forge-refresh
```

Try single plugin install:

claude plugin install product-design@product-forge-marketplace

Check Claude Code logs: Look in your Claude Code settings for detailed error logs if the above steps don't resolve the issue.

If marketplace is not registered

The script will automatically attempt to re-add the marketplace during reinstallation. If this fails, you can manually add it:

claude plugin marketplace add /Users/jeremiepoutrin/projects/github/jpoutrin/product-forge

If plugins still don't work after refresh

Restart Claude Code
Close all Claude Code windows and reopen
Check your internet connection
Review Claude Code logs for system errors

Related Commands

Command	Purpose
`/forge-help`	List all available Product Forge agents, skills, and commands

Related Scripts

Script	Purpose
`./scripts/validate-all-plugins.sh`	Validate all plugins or a specific plugin
`./scripts/validate-marketplace.py`	Validate marketplace.json schema
`./scripts/generate-forge-index.py`	Regenerate command/skill/agent index

Install forge-refresh and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# forge-refresh **Category**: Plugin Management ## Usage ```bash /forge-refresh [options] [plugin-name] ``` ## Options | Option | Description | |--------|-------------| | `--dry-run` | Preview actions without making changes | | `--force` | Force reinstall even if all plugins are up to date | | `--status` | Show current cache status only (no changes made) | | `--verbose` | Show detailed issue descriptions for each plugin | | `[plugin-name]` | Optional: Refresh only specific plugin (e.g., `product-design`) | ## Purpose Validates Product Forge plugin cache state and refreshes outdated, corrupted, or invalid plugins. Use this command when: - Claude Code becomes unstable or unresponsive - Plugins don't appear or respond in Claude Code - Skills, commands, or agents are not recognized - After pulling updates to the source repository - When cache appears to be out of sync with source ## How It Works This command performs six phases of cache management: 1. **Prerequisites** - Verifies claude CLI, git, and jq are available 2. **Detection** - Scans plugin cache and compares with source repository 3. **Reporting** - Shows status of each plugin and any issues found 4. **Backup** - Creates timestamped backup of current installation state 5. **Reinstallation** - Clears stale cache and reinstalls plugins 6. **Verification** - Confirms installations succeeded and match source ## What Gets Checked For each plugin, the command validates: - **SHA Match**: Installed version matches source repository commit - **Cache Exists**: Plugin cache directory is present - **Plugin Valid**: Plugin structure passes validation checks Status indicators: - ✅ **OK** - Plugin is up to date and valid - ⚠️ **OUTDATED** - Source has newer commits - ❌ **CORRUPTED** - Cache directory missing - ❌ **INVALID** - Plugin structure validation failed - ⭕ **MISSING** - Plugin not installed at all ## Execution Instructions for Claude Code When this command is run, Claude Code should: ### 1. Parse the Arguments Extract flags and plugin name from the command arguments: - `--dry-run`, `--force`, `--status`, `--verbose` are boolean flags - The last argument (if not a flag) is the optional plugin name ### 2. Delegate to Script Run the refresh script with all provided arguments: ```bash ./scripts/refresh-plugins.sh "$@" ``` ### 3. Interpret the Output The script will display: - Status report with emoji indicators for each plugin - List of issues detected (if any) - Prompts for confirmation (unless `--force` or `--dry-run`) - Progress during installation - Final summary with results ### 4. Exit Codes The script exits with: - `0` - Success (all plugins refreshed successfully) - `1` - Failure (some plugins failed to install, or prerequisites missing) - `2` - (reserved for future use) ### 5. Display Results Display all output from the script to the user. If there are failures: 1. Suggest checking the troubleshooting section in the output 2. Offer to run individual diagnostics like `./scripts/validate-all-plugins.sh` 3. Recommend checking Claude Code logs if the issue persists ## Examples ### Check current cache status ```bash /forge-refresh --status ``` Output shows status of all plugins without making any changes. ### Preview what would be refreshed ```bash /forge-refresh --dry-run ``` Shows exactly what actions would be taken, but makes no changes. ### Refresh with detailed output ```bash /forge-refresh --verbose ``` Shows status of all plugins with detailed issue descriptions. ### Force refresh all plugins ```bash /forge-refresh --force ``` Reinstalls all plugins regardless of current status. Use when you want a clean slate. ### Refresh specific plugin only ```bash /forge-refresh product-design ``` Only clears and reinstalls the `product-design` plugin, leaving others untouched. ### Combine options ```bash /forge-refresh --dry-run --verbose ``` Preview with detailed issue descriptions, no changes made. ## Common Scenarios ### Scenario 1: After pulling source updates ```bash git pull /forge-refresh ``` Refresh plugins after pulling new commits to match the updated source. ### Scenario 2: Plugins not appearing in Claude ```bash /forge-refresh --force ``` Force a complete reinstall if plugins became invisible or unresponsive. ### Scenario 3: Check without making changes ```bash /forge-refresh --dry-run ``` Preview what would be done before proceeding with actual refresh. ### Scenario 4: Diagnose single plugin issue ```bash /forge-refresh --verbose product-design ``` Check the status of a specific plugin with detailed diagnostic information. ## Troubleshooting ### If the command fails The script will suggest troubleshooting steps in its output. Common next steps: 1. **Verify plugins are valid:** ```bash ./scripts/validate-all-plugins.sh ``` 2. **Check if source repo is up to date:** ```bash git pull /forge-refresh ``` 3. **Try single plugin install:** ```bash claude plugin install product-design@product-forge-marketplace ``` 4. **Check Claude Code logs:** Look in your Claude Code settings for detailed error logs if the above steps don't resolve the issue. ### If marketplace is not registered The script will automatically attempt to re-add the marketplace during reinstallation. If this fails, you can manually add it: ```bash claude plugin marketplace add /Users/jeremiepoutrin/projects/github/jpoutrin/product-forge ``` ### If plugins still don't work after refresh - Restart Claude Code - Close all Claude Code windows and reopen - Check your internet connection - Review Claude Code logs for system errors ## Related Commands | Command | Purpose | |---------|---------| | `/forge-help` | List all available Product Forge agents, skills, and commands | ## Related Scripts | Script | Purpose | |--------|---------| | `./scripts/validate-all-plugins.sh` | Validate all plugins or a specific plugin | | `./scripts/validate-marketplace.py` | Validate marketplace.json schema | | `./scripts/generate-forge-index.py` | Regenerate command/skill/agent index |

{ "prompt": "# forge-refresh\n\n**Category**: Plugin Management\n\n## Usage\n\n```bash\n/forge-refresh [options] [plugin-name]\n```\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--dry-run` | Preview actions without making changes |\n| `--force` | Force reinstall even if all plugins are up to date |\n| `--status` | Show current cache status only (no changes made) |\n| `--verbose` | Show detailed issue descriptions for each plugin |\n| `[plugin-name]` | Optional: Refresh only specific plugin (e.g., `product-design`) |\n\n## Purpose\n\nValidates Product Forge plugin cache state and refreshes outdated, corrupted, or invalid plugins. Use this command when:\n\n- Claude Code becomes unstable or unresponsive\n- Plugins don't appear or respond in Claude Code\n- Skills, commands, or agents are not recognized\n- After pulling updates to the source repository\n- When cache appears to be out of sync with source\n\n## How It Works\n\nThis command performs six phases of cache management:\n\n1. **Prerequisites** - Verifies claude CLI, git, and jq are available\n2. **Detection** - Scans plugin cache and compares with source repository\n3. **Reporting** - Shows status of each plugin and any issues found\n4. **Backup** - Creates timestamped backup of current installation state\n5. **Reinstallation** - Clears stale cache and reinstalls plugins\n6. **Verification** - Confirms installations succeeded and match source\n\n## What Gets Checked\n\nFor each plugin, the command validates:\n\n- **SHA Match**: Installed version matches source repository commit\n- **Cache Exists**: Plugin cache directory is present\n- **Plugin Valid**: Plugin structure passes validation checks\n\nStatus indicators:\n- ✅ **OK** - Plugin is up to date and valid\n- ⚠️ **OUTDATED** - Source has newer commits\n- ❌ **CORRUPTED** - Cache directory missing\n- ❌ **INVALID** - Plugin structure validation failed\n- ⭕ **MISSING** - Plugin not installed at all\n\n## Execution Instructions for Claude Code\n\nWhen this command is run, Claude Code should:\n\n### 1. Parse the Arguments\n\nExtract flags and plugin name from the command arguments:\n- `--dry-run`, `--force`, `--status`, `--verbose` are boolean flags\n- The last argument (if not a flag) is the optional plugin name\n\n### 2. Delegate to Script\n\nRun the refresh script with all provided arguments:\n\n```bash\n./scripts/refresh-plugins.sh \"$@\"\n```\n\n### 3. Interpret the Output\n\nThe script will display:\n- Status report with emoji indicators for each plugin\n- List of issues detected (if any)\n- Prompts for confirmation (unless `--force` or `--dry-run`)\n- Progress during installation\n- Final summary with results\n\n### 4. Exit Codes\n\nThe script exits with:\n- `0` - Success (all plugins refreshed successfully)\n- `1` - Failure (some plugins failed to install, or prerequisites missing)\n- `2` - (reserved for future use)\n\n### 5. Display Results\n\nDisplay all output from the script to the user. If there are failures:\n\n1. Suggest checking the troubleshooting section in the output\n2. Offer to run individual diagnostics like `./scripts/validate-all-plugins.sh`\n3. Recommend checking Claude Code logs if the issue persists\n\n## Examples\n\n### Check current cache status\n\n```bash\n/forge-refresh --status\n```\n\nOutput shows status of all plugins without making any changes.\n\n### Preview what would be refreshed\n\n```bash\n/forge-refresh --dry-run\n```\n\nShows exactly what actions would be taken, but makes no changes.\n\n### Refresh with detailed output\n\n```bash\n/forge-refresh --verbose\n```\n\nShows status of all plugins with detailed issue descriptions.\n\n### Force refresh all plugins\n\n```bash\n/forge-refresh --force\n```\n\nReinstalls all plugins regardless of current status. Use when you want a clean slate.\n\n### Refresh specific plugin only\n\n```bash\n/forge-refresh product-design\n```\n\nOnly clears and reinstalls the `product-design` plugin, leaving others untouched.\n\n### Combine options\n\n```bash\n/forge-refresh --dry-run --verbose\n```\n\nPreview with detailed issue descriptions, no changes made.\n\n## Common Scenarios\n\n### Scenario 1: After pulling source updates\n\n```bash\ngit pull\n/forge-refresh\n```\n\nRefresh plugins after pulling new commits to match the updated source.\n\n### Scenario 2: Plugins not appearing in Claude\n\n```bash\n/forge-refresh --force\n```\n\nForce a complete reinstall if plugins became invisible or unresponsive.\n\n### Scenario 3: Check without making changes\n\n```bash\n/forge-refresh --dry-run\n```\n\nPreview what would be done before proceeding with actual refresh.\n\n### Scenario 4: Diagnose single plugin issue\n\n```bash\n/forge-refresh --verbose product-design\n```\n\nCheck the status of a specific plugin with detailed diagnostic information.\n\n## Troubleshooting\n\n### If the command fails\n\nThe script will suggest troubleshooting steps in its output. Common next steps:\n\n1. **Verify plugins are valid:**\n ```bash\n ./scripts/validate-all-plugins.sh\n ```\n\n2. **Check if source repo is up to date:**\n ```bash\n git pull\n /forge-refresh\n ```\n\n3. **Try single plugin install:**\n ```bash\n claude plugin install product-design@product-forge-marketplace\n ```\n\n4. **Check Claude Code logs:**\n Look in your Claude Code settings for detailed error logs if the above steps don't resolve the issue.\n\n### If marketplace is not registered\n\nThe script will automatically attempt to re-add the marketplace during reinstallation. If this fails, you can manually add it:\n\n```bash\nclaude plugin marketplace add /Users/jeremiepoutrin/projects/github/jpoutrin/product-forge\n```\n\n### If plugins still don't work after refresh\n\n- Restart Claude Code\n- Close all Claude Code windows and reopen\n- Check your internet connection\n- Review Claude Code logs for system errors\n\n## Related Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/forge-help` | List all available Product Forge agents, skills, and commands |\n\n## Related Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `./scripts/validate-all-plugins.sh` | Validate all plugins or a specific plugin |\n| `./scripts/validate-marketplace.py` | Validate marketplace.json schema |\n| `./scripts/generate-forge-index.py` | Regenerate command/skill/agent index |", "variables": [], "notes": "Validate and refresh Product Forge plugin cache Arguments: [--dry-run] [--force] [--status] [--verbose] [plugin-name].", "metadata": { "source": { "provider": "github-claude-commands", "repository": "https://github.com/jpoutrin/product-forge", "path": ".claude/commands/forge-refresh.md", "ref": "0ebe7aea08747cb1c121bc77652d458b9e8ee782", "url": "https://github.com/jpoutrin/product-forge/blob/0ebe7aea08747cb1c121bc77652d458b9e8ee782/.claude/commands/forge-refresh.md", "key": "jpoutrin/product-forge/.claude/commands/forge-refresh.md" } } }

forge-refresh

About

forge-refresh

Usage

Options

Purpose

How It Works

What Gets Checked

Execution Instructions for Claude Code

1. Parse the Arguments

2. Delegate to Script

3. Interpret the Output

4. Exit Codes

5. Display Results

Examples

Check current cache status

Preview what would be refreshed

Refresh with detailed output

Force refresh all plugins

Refresh specific plugin only

Combine options

Common Scenarios

Scenario 1: After pulling source updates

Scenario 2: Plugins not appearing in Claude

Scenario 3: Check without making changes

Scenario 4: Diagnose single plugin issue

Troubleshooting

If the command fails

If marketplace is not registered

If plugins still don't work after refresh

Related Commands

Related Scripts

Install forge-refresh and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews