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

Phase 1: Backend Foundation

1.1 Database Migrations

• 1.1.1 Create Alembic migration for tool_types (add definition_type, dockerfile_template, build_context, readiness_probe)
• 1.1.2 Create Alembic migration for tool_configs (add port_override, start_command, working_directory, environment_variables, volumes)
• 1.1.3 Create Alembic migration for config_folders (new table)
• 1.1.4 Add CHECK constraints (definition_type enum, port range)
• 1.1.5 Add indexes for config_folders
• 1.1.6 Run migrations locally and verify with test data

1.2 Model Updates

• 1.2.1 Update ToolType model with new fields
• 1.2.2 Update ToolConfig model with new fields
• 1.2.3 Create ConfigFolder model
• 1.2.4 Add Pydantic schemas for ConfigFolder (create, update, response)
• 1.2.5 Update Pydantic schemas for ToolType (add new fields)
• 1.2.6 Update Pydantic schemas for ToolConfig (add new fields)
• 1.2.7 Add validation schemas (port range, JSON structure, definition_type enum)

1.3 Config Folder API

• 1.3.1 Create api/config_folders.py router
• 1.3.2 Implement GET /config-folders (list with filtering by project)
• 1.3.3 Implement POST /config-folders (create)
• 1.3.4 Implement PUT /config-folders/{id} (update name, mount_path, files)
• 1.3.5 Implement DELETE /config-folders/{id} (delete)
• 1.3.6 Implement POST /config-folders/{id}/overrides (add project override)
• 1.3.7 Implement PUT /config-folders/{id}/overrides/{project_id} (update override)
• 1.3.8 Implement DELETE /config-folders/{id}/overrides/{project_id} (remove override)
• 1.3.9 Add validation: 10MB size limit per folder
• 1.3.10 Add ownership checks (user can only access own folders)

1.4 Tool Type API Updates

• 1.4.1 Update POST /tool-types to accept definition_type, dockerfile_template, build_context, readiness_probe
• 1.4.2 Update PUT /tool-types/{id} to handle new fields
• 1.4.3 Add GET /tool-types/{id}/validate endpoint (syntax validation)
• 1.4.4 Update tool type response schemas
• 1.4.5 Update seed function to set definition_type="compose" for built-in types

1.5 Tool Config API Updates

• 1.5.1 Update POST /tool-configs to accept new fields
• 1.5.2 Update PUT /tool-configs/{id} to handle new fields
• 1.5.3 Update GET /tool-configs to return new fields
• 1.5.4 Add GET /tool-configs/defaults/{tool_type_id} endpoint
• 1.5.5 Add validation for port_override range
• 1.5.6 Add validation for environment_variables JSON structure
• 1.5.7 Add validation for volumes JSON structure (source/target/type)

Phase 2: Instance Creation Enhancement

2.1 Docker Build Service

• 2.1.1 Create services/docker_build.py for Dockerfile builds
• 2.1.2 Implement build_image(instance_dir, dockerfile, tag) function
• 2.1.3 Handle build context file writing
• 2.1.4 Add build output streaming/logging
• 2.1.5 Handle build failures with clear error messages

2.2 Compose Generation for Dockerfile Tools

• 2.2.1 Create compose template for dockerfile-built images
• 2.2.2 Integrate build service into instance creation flow
• 2.2.3 Update render_compose_template to handle both paths

2.3 Config Folder Mounting

• 2.3.1 Implement write_config_folder_files(instance_dir, folders) function
• 2.3.2 Resolve config folders for user + project
• 2.3.3 Generate volume mounts in compose file for config folders
• 2.3.4 Apply project overrides during resolution
• 2.3.5 Write config folder files to instance_dir/volumes/

2.4 Readiness Probe Service

• 2.4.1 Create services/readiness_probe.py
• 2.4.2 Implement execute_probe(container_id, probe_config) function
• 2.4.3 Implement polling loop with timeout and interval
• 2.4.4 Store probe output/logs on instance
• 2.4.5 Update instance status based on probe result ("running" or "failed")
• 2.4.6 Handle probe command failures gracefully

2.5 Instance Creation Integration

• 2.5.1 Update create_instance endpoint to use new fields
• 2.5.2 Integrate dockerfile build path into creation flow
• 2.5.3 Integrate config folder mounting
• 2.5.4 Integrate readiness probe execution
• 2.5.5 Apply port_override if specified
• 2.5.6 Apply start_command if specified
• 2.5.7 Apply working_directory if specified
• 2.5.8 Apply environment_variables from ToolConfig
• 2.5.9 Apply volumes from ToolConfig
• 2.5.10 Test end-to-end instance creation with all new features

Phase 3: Frontend UI

3.1 API Client Updates

• 3.1.1 Update api/tool_types.ts with new fields and endpoints
• 3.1.2 Update api/tool_configs.ts with new fields
• 3.1.3 Create api/config_folders.ts with all CRUD operations
• 3.1.4 Update TypeScript types/interfaces

3.2 Tool Workshop Layout

• 3.2.1 Create pages/tool-workshop.tsx (replaces tool-configs and tool-types)
• 3.2.2 Implement split-pane layout (sidebar + main content)
• 3.2.3 Create sidebar navigation tree (Tool Types / Config Folders)
• 3.2.4 Implement tab switching (Tool Types / Configs / Config Folders)
• 3.2.5 Add responsive design (collapsible sidebar on mobile)
• 3.2.6 Update App.tsx routing

3.3 Tool Type Builder

• 3.3.1 Create components/ToolTypeBuilder.tsx
• 3.3.2 Implement definition type selector (Compose vs Dockerfile)
• 3.3.3 Create compose template editor (textarea with YAML highlighting)
• 3.3.4 Create dockerfile editor (textarea with Dockerfile highlighting)
• 3.3.5 Add build context file manager
• 3.3.6 Add readiness probe configuration (command, timeout, interval)
• 3.3.7 Add validation feedback (syntax check)
• 3.3.8 Implement create/update/delete operations

3.4 Config Editor Enhancement

• 3.4.1 Update config form with new fields
• 3.4.2 Add port override input (integer, 1-65535)
• 3.4.3 Add start command input
• 3.4.4 Add working directory input
• 3.4.5 Create environment variables editor (key-value table)
• 3.4.6 Create volumes editor (source/target/type table)
• 3.4.7 Add JSON validation for env vars and volumes
• 3.4.8 Implement tabbed sections (Basic / Runtime / Advanced)

3.5 Config Folder Manager

• 3.5.1 Create components/ConfigFolderManager.tsx
• 3.5.2 Implement folder list view
• 3.5.3 Create folder editor (name, description, mount_path)
• 3.5.4 Create file manager (add/edit/delete files with path and content)
• 3.5.5 Implement file content editor (textarea with syntax highlighting)
• 3.5.6 Create project override manager
• 3.5.7 Add active/inactive toggle
• 3.5.8 Show folder size indicator

3.6 Navigation Updates

• 3.6.1 Update header/navigation to link to /tool-workshop
• 3.6.2 Remove old /tool-configs and /tool-types routes (or redirect)
• 3.6.3 Update breadcrumb navigation if applicable

Phase 4: Integration & Testing

4.1 Backend Testing

• 4.1.1 Test config folder CRUD operations
• 4.1.2 Test config folder project overrides
• 4.1.3 Test tool type creation with dockerfile
• 4.1.4 Test tool type creation with compose
• 4.1.5 Test readiness probe execution (success case)
• 4.1.6 Test readiness probe execution (timeout case)
• 4.1.7 Test instance creation with config folders mounted
• 4.1.8 Test instance creation with port override
• 4.1.9 Test instance creation with volumes
• 4.1.10 Test 10MB size limit enforcement

4.2 Frontend Testing

• 4.2.1 Test Tool Workshop page load
• 4.2.2 Test tool type creation flow
• 4.2.3 Test config folder creation and file management
• 4.2.4 Test config editor with all new fields
• 4.2.5 Test responsive layout on mobile
• 4.2.6 Test form validation (port range, JSON structure)

4.3 End-to-End Testing

• 4.3.1 Create a new tool type with dockerfile, start instance
• 4.3.2 Create a new tool type with compose, start instance
• 4.3.3 Create config folder, mount into instance, verify files present
• 4.3.4 Add project override, verify different files in different projects
• 4.3.5 Test readiness probe with failing command (should mark failed)
• 4.3.6 Test readiness probe with succeeding command (should mark running)

4.4 Quality Gates

• 4.4.1 Run backend linting (ruff)
• 4.4.2 Run backend type checking (mypy)
• 4.4.3 Run frontend type checking (tsc)
• 4.4.4 Run frontend linting (eslint)
• 4.4.5 Build frontend and verify no errors
• 4.4.6 Run existing tests to ensure no regressions
• 4.4.7 Verify backward compatibility (existing instances still work)

Phase 5: Documentation & Deployment

5.1 Documentation

• 5.1.1 Update API documentation (OpenAPI/Swagger annotations)
• 5.1.2 Add tool workshop user guide
• 5.1.3 Document config folder usage
• 5.1.4 Document readiness probe configuration
• 5.1.5 Add example dockerfile and compose templates

5.2 Migration & Deployment

• 5.2.1 Verify database migrations run cleanly on existing data
• 5.2.2 Update seed data for built-in tool types (add definition_type)
• 5.2.3 Test fresh install (no existing data)
• 5.2.4 Commit all changes with conventional commit messages
• 5.2.5 Create comprehensive PR description

Quality Gates Summary

Before completing this change:

• All migrations must run successfully
• Backend linting and type checking must pass
• Frontend build must succeed with no errors
• All new API endpoints must be tested
• At least one end-to-end test for each new feature
• No regressions in existing instance creation flow
• Documentation updated