tasks.json

{
  "metadata": {
    "created": "2025-12-06T00:00:00Z",
    "updated": "2025-12-06T00:00:00Z",
    "feature": "daemon-architecture",
    "phase": "implementation",
    "risk_level": "high",
    "estimated_effort": "40-60 hours",
    "description": "Migrate devtool-mcp to daemon-based architecture with persistent state"
  },
  "tasks": [
    {
      "id": "task-001",
      "description": "Create protocol package with command/response types and parser",
      "passes": false,
      "priority": "critical",
      "risk": "medium",
      "phase": 1,
      "verification": "go test -v ./internal/protocol/... && go build ./...",
      "files": [
        "internal/protocol/commands.go",
        "internal/protocol/responses.go",
        "internal/protocol/parser.go",
        "internal/protocol/parser_test.go"
      ],
      "dependencies": [],
      "notes": "Define all command types (RUN, PROC, PROXY, etc.) and response formats (OK, ERR, JSON, CHUNK, END). Parser must handle length-prefixed data and chunked responses.",
      "context": {
        "documentation": "docs/daemon-architecture.md#text-protocol-specification"
      }
    },
    {
      "id": "task-002",
      "description": "Implement socket management for Unix domain sockets",
      "passes": false,
      "priority": "critical",
      "risk": "medium",
      "phase": 1,
      "verification": "go test -v ./internal/daemon/... -run TestSocket",
      "files": [
        "internal/daemon/socket.go",
        "internal/daemon/socket_unix.go",
        "internal/daemon/socket_windows.go",
        "internal/daemon/socket_test.go"
      ],
      "dependencies": [],
      "notes": "Use build tags for platform-specific implementations. Handle stale socket detection and cleanup. Socket path: $XDG_RUNTIME_DIR/devtool-mcp.sock or /tmp/devtool-mcp-$UID.sock",
      "context": {
        "similar_code": "Standard library net.Listen(\"unix\", path)"
      }
    },
    {
      "id": "task-003",
      "description": "Create daemon core with connection handling and main loop",
      "passes": false,
      "priority": "critical",
      "risk": "high",
      "phase": 1,
      "verification": "go test -v ./internal/daemon/... -run TestDaemon",
      "files": [
        "internal/daemon/daemon.go",
        "internal/daemon/connection.go",
        "internal/daemon/daemon_test.go"
      ],
      "dependencies": ["task-001", "task-002"],
      "notes": "Daemon owns ProcessManager and ProxyManager. Accept connections, spawn goroutine per client. Handle graceful shutdown with SIGTERM/SIGINT. Use sync.Map for client tracking.",
      "context": {
        "similar_code": "cmd/devtool-mcp/main.go:23-93 (current server setup)"
      }
    },
    {
      "id": "task-004",
      "description": "Implement daemon command handlers for all existing tools",
      "passes": false,
      "priority": "critical",
      "risk": "medium",
      "phase": 2,
      "verification": "go test -v ./internal/daemon/... -run TestHandler",
      "files": [
        "internal/daemon/handler.go",
        "internal/daemon/handler_process.go",
        "internal/daemon/handler_proxy.go",
        "internal/daemon/handler_project.go",
        "internal/daemon/handler_test.go"
      ],
      "dependencies": ["task-003"],
      "notes": "Each handler parses command, calls existing ProcessManager/ProxyManager methods, formats response. Reuse existing logic from internal/tools/*.go where possible.",
      "context": {
        "similar_code": "internal/tools/process.go:245-262 (existing handlers)"
      }
    },
    {
      "id": "task-005",
      "description": "Create protocol client for connecting to daemon",
      "passes": false,
      "priority": "critical",
      "risk": "medium",
      "phase": 3,
      "verification": "go test -v ./internal/client/... -run TestClient",
      "files": [
        "internal/client/client.go",
        "internal/client/client_test.go"
      ],
      "dependencies": ["task-001"],
      "notes": "Buffered reader/writer for efficient I/O. Send commands, parse responses. Handle chunked responses for streaming output. Thread-safe for concurrent tool calls.",
      "context": {
        "documentation": "docs/daemon-architecture.md#mcp-client"
      }
    },
    {
      "id": "task-006",
      "description": "Implement daemon auto-start logic in client",
      "passes": false,
      "priority": "high",
      "risk": "high",
      "phase": 3,
      "verification": "go test -v ./internal/client/... -run TestAutoStart",
      "files": [
        "internal/client/autostart.go",
        "internal/client/autostart_test.go"
      ],
      "dependencies": ["task-005"],
      "notes": "Detect if daemon running (try connect). If not, spawn daemon process. Wait for socket with exponential backoff. Handle race conditions (two clients starting daemon simultaneously).",
      "context": {
        "documentation": "docs/daemon-architecture.md#auto-start-logic"
      }
    },
    {
      "id": "task-007",
      "description": "Update MCP tool handlers to use daemon client",
      "passes": false,
      "priority": "critical",
      "risk": "high",
      "phase": 3,
      "verification": "go test -v ./internal/tools/... && go build ./...",
      "files": [
        "internal/tools/process.go",
        "internal/tools/proxy_tools.go",
        "internal/tools/project.go"
      ],
      "dependencies": ["task-005", "task-006"],
      "notes": "Each tool handler: get/create client, call EnsureConnected(), send command, parse response, return MCP result. Maintain backwards compatibility - same MCP interface.",
      "context": {
        "similar_code": "internal/tools/process.go:131-243 (current implementation)"
      }
    },
    {
      "id": "task-008",
      "description": "Add daemon management MCP tool",
      "passes": false,
      "priority": "high",
      "risk": "low",
      "phase": 4,
      "verification": "go test -v ./internal/tools/... -run TestDaemon",
      "files": [
        "internal/tools/daemon.go",
        "internal/tools/daemon_test.go"
      ],
      "dependencies": ["task-007"],
      "notes": "New 'daemon' tool with actions: status, start, stop, restart, info. Uses client for status/info, direct process control for start/stop. Register in main.go.",
      "context": {
        "documentation": "docs/daemon-architecture.md#daemon-management-tool"
      }
    },
    {
      "id": "task-009",
      "description": "Update main.go to support daemon and client modes",
      "passes": false,
      "priority": "critical",
      "risk": "medium",
      "phase": 4,
      "verification": "./devtool-mcp daemon --help && ./devtool-mcp --help && go build ./...",
      "files": [
        "cmd/devtool-mcp/main.go"
      ],
      "dependencies": ["task-003", "task-007", "task-008"],
      "notes": "Default mode: MCP client (current behavior). 'daemon' subcommand: run as daemon. Use flag or os.Args[1] to detect mode. Keep single binary.",
      "context": {
        "similar_code": "cmd/devtool-mcp/main.go (current entry point)"
      }
    },
    {
      "id": "task-010",
      "description": "Add Windows named pipe support",
      "passes": false,
      "priority": "medium",
      "risk": "medium",
      "phase": 5,
      "verification": "GOOS=windows go build ./... && go test -v ./internal/daemon/... -run TestSocket",
      "files": [
        "internal/daemon/socket_windows.go"
      ],
      "dependencies": ["task-002"],
      "notes": "Use \\\\.\\pipe\\devtool-mcp-$USERNAME. Windows named pipes have different semantics - review golang.org/x/sys/windows for CreateNamedPipe.",
      "context": {
        "external_ref": "https://pkg.go.dev/golang.org/x/sys/windows"
      }
    },
    {
      "id": "task-011",
      "description": "Create integration tests for full daemon lifecycle",
      "passes": false,
      "priority": "high",
      "risk": "low",
      "phase": 6,
      "verification": "go test -v ./internal/daemon/... -run TestIntegration -timeout 60s",
      "files": [
        "internal/daemon/integration_test.go"
      ],
      "dependencies": ["task-009"],
      "notes": "Test: start daemon, connect client, run commands, disconnect, reconnect (state persists), stop daemon. Test multi-client scenarios. Test stale socket cleanup.",
      "context": {}
    },
    {
      "id": "task-012",
      "description": "Create multi-client concurrency tests",
      "passes": false,
      "priority": "high",
      "risk": "low",
      "phase": 6,
      "verification": "go test -v ./internal/daemon/... -run TestConcurrency -race -timeout 60s",
      "files": [
        "internal/daemon/concurrency_test.go"
      ],
      "dependencies": ["task-011"],
      "notes": "Test multiple clients sending commands simultaneously. Verify lock-free design holds. Test process/proxy operations from different clients. Use -race flag.",
      "context": {}
    },
    {
      "id": "task-013",
      "description": "Update documentation for daemon architecture",
      "passes": false,
      "priority": "medium",
      "risk": "low",
      "phase": 6,
      "verification": "cat CLAUDE.md | grep -q daemon && cat README.md | grep -q daemon",
      "files": [
        "CLAUDE.md",
        "README.md",
        "docs-site/docs/features/daemon-mode.md",
        "docs-site/docs/api/daemon.md"
      ],
      "dependencies": ["task-009"],
      "notes": "Update CLAUDE.md with daemon architecture section. Add daemon mode docs to Docusaurus site. Update README quick start with daemon info.",
      "context": {}
    },
    {
      "id": "task-014",
      "description": "Add daemon health check and auto-restart",
      "passes": false,
      "priority": "medium",
      "risk": "medium",
      "phase": 6,
      "verification": "go test -v ./internal/daemon/... -run TestHealth",
      "files": [
        "internal/daemon/health.go",
        "internal/daemon/health_test.go"
      ],
      "dependencies": ["task-003"],
      "notes": "Periodic health check in daemon (detect stuck processes). Client-side: if daemon unresponsive, try restart. Add PING/PONG command for liveness check.",
      "context": {}
    }
  ]
}