headquarter/openspec/tasks/tool-definition-manifest.md

Tasks: Tool Definition Manifest System

PR 1: Backend Manifest System

T1.1 Database Migration

• Create tool_definition_manifests table
• Add manifest_id, definition_type to tool_types
• Add manifest_compiled_at, image_tag to tool_instances
• Data migration: convert pi-agent to manifest

T1.2 Models

• ToolDefinitionManifest SQLAlchemy model
• Update ToolType model with manifest relationship
• Update ToolInstance model with image_tag

T1.3 Manifest Compiler

• resolve_base() — deep merge base + tool manifest
• compile_dockerfile() — generate Dockerfile from manifest
• compile_entrypoint() — generate startup entrypoint script
• compile_compose() — generate Compose from manifest
• compute_image_tag() — deterministic hash-based tag
• resolve_mount_source() — mount source resolution

T1.4 Permission Fixer

• apply_mount_permissions() — post-start chown/chmod
• Handle missing root user gracefully
• Timeout and error reporting

T1.5 API Endpoints

• POST /tool-definitions — create
• GET /tool-definitions — list
• GET /tool-definitions/{id} — get
• PUT /tool-definitions/{id} — update
• DELETE /tool-definitions/{id} — delete
• POST /tool-definitions/{id}/compile — preview

T1.6 Modified Startup Flow

• Update start_instance to use manifest when definition_type == "manifest"
• Integrate permission fixer post-start
• Store image_tag on instance for reuse

T1.7 Tests

• Unit: manifest compiler (all package managers, base merge)
• Unit: permission fixer (success, failure, timeout)
• Unit: mount resolution (all source types)
• Integration: manifest → build → start → terminal works
• Integration: legacy tool types still work

---

PR 2: Frontend Tool Workshop

T2.1 Tool Definitions API Client

• Add tool definition endpoints to client.ts
• Type definitions for manifest schema

T2.2 Tool Workshop Page

• Base image selector (with version dropdown)
• Package manager editors (apt list, npm list, node version)
• Script editors (build vs startup, tabbed)
• Mount schema designer (form table with add/remove)
• Runtime config (command, working_dir, stdin_open, tty)

T2.3 Live Preview

• Preview panel showing generated Dockerfile
• Preview panel showing generated Compose
• "Compile" button calling API preview endpoint

T2.4 Tool Definitions List

• Table view of all definitions
• Create / Edit / Delete actions
• Base indicator (shows if it's a base definition)

---

PR 3: Migration & Legacy Fallback

T3.1 Data Migration

• Alembic migration creating base definition + pi-agent manifest
• Update existing pi-agent tool_type row

T3.2 Legacy Fallback

• Ensure definition_type == "legacy" still uses old flow
• Ensure dockerfile_template / compose_template still work
• Tests for legacy path

T3.3 Documentation

• Update API docs
• Add Tool Workshop user guide