Support plugin command directories for extensible command discovery #323

New issue

Closed

opened 2026-03-30 07:19:04 +00:00 by mprihoda · 1 comment

mprihoda commented

2026-03-30 07:19:04 +00:00

(Migrated from github.com)

Context

As part of the kanon/iw-cli relationship redesign (see iterative-works/dev-docs#123), we're extracting AI-specific commands (like batch-implement, implement) from iw-cli core into platform-specific plugins (e.g., kanon's Claude Code plugin). This requires iw-cli to support loading commands from external directories beyond the current two search paths (shared + project-local).

Current State

iw-run resolves commands from two directories:

Shared commands: $IW_COMMANDS_DIR (from iw-cli installation)
Project commands: $PROJECT_DIR/.iw/commands/ (invoked with ./ prefix)

Proposed Change

Plugin Command Directories

Add support for additional command directories registered by plugins. Resolution order:

Project commands (./name) — project-local, highest priority
Plugin commands — from registered plugin directories
Shared commands — from iw-cli core installation

Registration Mechanism

Support both:

Environment variable: IW_PLUGIN_DIRS (colon-separated paths) for ad-hoc use
Config file: entries in .iw/config.conf for persistent registration
Auto-discovery: scan $XDG_DATA_HOME/iw/plugins/*/commands/ for installed plugins

Command Listing

./iw --list should show plugin commands in a separate section (like project commands already are), with the plugin name/source clearly indicated:

Available commands:
  ...core commands...

Plugin commands (kanon):
  Command: batch-implement
  Purpose: Orchestrate multi-phase AI-assisted implementation
  ...

Project commands (use ./name):
  ...

Version Compatibility

Add a // REQUIRES: <version> header convention to command files. iw-run checks this before attempting compilation and gives a human-readable error:

Error: Command 'batch-implement' (from plugin 'kanon') requires iw-cli >= 0.5.0
You have: 0.4.2
Update with: ./iw --self-update

This is preferred over letting scala-cli produce opaque compilation errors when plugin commands use core APIs that don't exist in the installed version.

Deployment

A plugin registers its commands by either:

A setup command: ./iw plugin install <path-or-name>
Writing a config entry pointing to its command directory
Placing commands in the auto-discovery directory

Key Considerations

Plugin commands compile against the same $IW_CORE_DIR as shared commands — no separate dependency management needed
Hooks (.hook-*.scala) should work for plugin commands too
--describe should indicate the command source (core/plugin/project)
Plugin commands should not be able to shadow core commands (or at least warn if they do)

iterative-works/dev-docs#123 — Integrate iw-cli into dev-docs (being redesigned as bounded context extraction instead)

## Context As part of the kanon/iw-cli relationship redesign (see iterative-works/dev-docs#123), we're extracting AI-specific commands (like `batch-implement`, `implement`) from iw-cli core into platform-specific plugins (e.g., kanon's Claude Code plugin). This requires iw-cli to support loading commands from external directories beyond the current two search paths (shared + project-local). ## Current State `iw-run` resolves commands from two directories: 1. **Shared commands**: `$IW_COMMANDS_DIR` (from iw-cli installation) 2. **Project commands**: `$PROJECT_DIR/.iw/commands/` (invoked with `./` prefix) ## Proposed Change ### Plugin Command Directories Add support for additional command directories registered by plugins. Resolution order: 1. **Project commands** (`./name`) — project-local, highest priority 2. **Plugin commands** — from registered plugin directories 3. **Shared commands** — from iw-cli core installation ### Registration Mechanism Support both: - **Environment variable**: `IW_PLUGIN_DIRS` (colon-separated paths) for ad-hoc use - **Config file**: entries in `.iw/config.conf` for persistent registration - **Auto-discovery**: scan `$XDG_DATA_HOME/iw/plugins/*/commands/` for installed plugins ### Command Listing `./iw --list` should show plugin commands in a separate section (like project commands already are), with the plugin name/source clearly indicated: ``` Available commands: ...core commands... Plugin commands (kanon): Command: batch-implement Purpose: Orchestrate multi-phase AI-assisted implementation ... Project commands (use ./name): ... ``` ### Version Compatibility Add a `// REQUIRES: <version>` header convention to command files. `iw-run` checks this before attempting compilation and gives a human-readable error: ``` Error: Command 'batch-implement' (from plugin 'kanon') requires iw-cli >= 0.5.0 You have: 0.4.2 Update with: ./iw --self-update ``` This is preferred over letting scala-cli produce opaque compilation errors when plugin commands use core APIs that don't exist in the installed version. ### Deployment A plugin registers its commands by either: - A setup command: `./iw plugin install <path-or-name>` - Writing a config entry pointing to its command directory - Placing commands in the auto-discovery directory ## Key Considerations - Plugin commands compile against the same `$IW_CORE_DIR` as shared commands — no separate dependency management needed - Hooks (`.hook-*.scala`) should work for plugin commands too - `--describe` should indicate the command source (core/plugin/project) - Plugin commands should not be able to shadow core commands (or at least warn if they do) ## Related - iterative-works/dev-docs#123 — Integrate iw-cli into dev-docs (being redesigned as bounded context extraction instead)

mprihoda commented

2026-04-01 18:23:38 +00:00

(Migrated from github.com)

Merged in PR #329 (bd5b5c1)

Merged in PR #329 (bd5b5c1)