headquarter/openspec/changes/archive/2026-05-22-tool-workshop/proposal.md

Why

The current tool system is too rigid. Tool types are hardcoded with compose templates, configs are simple key-value pairs, and the UI is a basic flat list. Users need a true "tool workshop" where they can:

1. Define new tools with either Docker Compose or Dockerfile
2. Configure rich tool settings including ports, commands, working directories, and volume mounts
3. Create reusable config file collections (e.g., dotfiles, IDE settings) that mount into containers
4. Wait for tools to be ready with configurable health/readiness probes before considering the build complete

This unlocks the platform from built-in tools to a true marketplace of user-defined and user-configured tools.

What Changes

• Enhance ToolType model: Add dockerfile_template, readiness_probe (command + timeout), build_context field
• Enhance ToolConfig model: Add port_override, start_command, working_directory, environment_variables, volumes
• Create ConfigFolder model: Named collections of files mountable as volumes, with per-project overrides
• Add readiness probe system: Instance creation waits for probe command with configurable timeout
• Unified Tool Workshop UI: Single page replacing /tool-configs and /tool-types with:
  • Tool Type builder (compose or dockerfile)
  • Tool Config editor (split-pane with all new fields)
  • Config Folder manager (file collections with mount paths)
  • Live validation and preview
• Update instance creation flow: Support dockerfile builds, mount config folders, apply readiness probes
• Database migrations: New columns on tool_types, tool_configs; new config_folders table

Capabilities

New Capabilities

• tool-workshop: Unified tool definition, configuration, and deployment interface
• config-folders: Reusable per-user file collections mountable into containers with per-project overrides
• readiness-probes: Build-time health checks that wait for tools to be ready before marking instances as running

Modified Capabilities

• tool-types: Enhanced with dockerfile support, readiness probes, build context
• tool-config-management: Extended with port overrides, volumes, environment variables, working directory
• tool-instances: Instance creation supports dockerfile builds, config folder mounts, probe waiting

Impact

• Backend:
  • Models: ToolType, ToolConfig, new ConfigFolder
  • API: New endpoints for config folders, updated tool type/config endpoints
  • Services: Docker build service (for dockerfiles), readiness probe service
  • Instance creation: Dockerfile build path, volume mounting, probe execution
• Frontend:
  • New ToolWorkshopPage component (replaces /tool-configs and /tool-types)
  • New components: Dockerfile editor, readiness probe config, config folder manager, volume mount editor
  • Updated routing and navigation
• Database:
  • tool_types: Add dockerfile_template, readiness_probe, build_context
  • tool_configs: Add port_override, start_command, working_directory, environment_variables, volumes
  • New config_folders table
• User Experience: Users can now define entirely new tools, configure them richly, and reuse config collections across projects

Supersedes

This change supersedes tool-config-ui-rework which scoped only to the UI rework and basic new fields. This is a comprehensive expansion of the tool system.