Cory Policht
← Back to the Devlog
DEVLOG · 2026-07-24 .. 2026-07-30 · RELEASE

Platform hits 1.0.

The umbrella AI-Dev-Platform repository cuts its v1.0.0 release. Behind the tag lies the local spine: repeatable, idempotent PowerShell scripts to cold-start the multi-service developer environment, hardened against Windows path confinement and port readiness quirks.

WINDOW
Start2026-07-24
End2026-07-30
Kindrelease
Projectsai-dev-platform
Delivered
  • ai-dev-platform
    AI-Dev-Platform v1.0.0 umbrella release
    Closes the v1.0.0 tail execution plan, accepts architecture decisions ADR-027 through ADR-029, and publishes the v1.0.0 umbrella platform tag.
    DeveloperAutomationToolsServices · v1.0.0
  • ai-dev-platform
    Idempotent local spine cold-start orchestration
    Introduces Start-LocalSpine and Stop-LocalSpine scripts to manage Postgres/Mongo containers, MCPServer, AIService, and Project Hub in dependency order.
    DeveloperAutomationToolsServices · 9d758bf
  • ai-dev-platform
    Windows spine bootstrapping and strict dependency readiness gates
    Resolves Windows path confinement failures on MCP workspace roots, sets required capability sidecars, and gates AIService startup on live MCPServer ports.
    DeveloperAutomationToolsServices · #42DeveloperAutomationToolsServices · 249b58b

Following the individual component releases earlier in the month, the parent umbrella repository—DeveloperAutomationToolsServices—tagged v1.0.0 on July 25. With foundational epics completed and three key architecture decision records accepted (ADR-027 webhook ingress, ADR-028 read-only machine execution, and ADR-029 session credential issuance), the platform closed its v1.0.0 tail execution plan.

Reaching 1.0 as an umbrella repo is not just a paperwork exercise; it means a developer can pull down the repositories and reliably run the entire stack locally.

To make that real, agent-claude-main authored the initial local spine automation (9d758bf). Start-LocalSpine.ps1 and Stop-LocalSpine.ps1 orchestrate the multi-service dependency chain: starting Docker containers for PostgreSQL and MongoDB, bringing up MCPServer, booting AIService under the local-spine profile, starting project-hub-api, and launching the frontend UIs. The automation was built to be idempotent, querying existing port bindings and container statuses before launching so engineers can re-run the script safely without creating orphaned processes.

Running the full spine on a Windows development machine quickly brought platform-specific assumptions to light. In PR #42, several cold-start blockers were fixed:

  1. Path confinement on Windows: MCPServer in Go defaulted its workspace root to "/workspace". On Linux, this is a valid absolute path. On Windows, filepath.IsAbs("/workspace") returns false because it lacks a drive letter, causing pathconfine to fail startup immediately. The launcher script now explicitly sets MCP_WORKSPACE_ROOT to the absolute Windows developer root.
  2. Missing capability sidecar: Starting MCPServer directly without setting MCP_CAPABILITY_SIDECAR silently downgraded all tools without an inline declaration to RequireApproval, causing test runs to behave unpredictably.
  3. Hard dependency readiness gating: When AIService starts up, its initial handshake fetches tool capabilities from MCPServer. If AIService booted before MCPServer was actually listening on :8080, it fell back to stale in-memory config metadata. PR #42 added an active Test-PortOpen check, refusing to launch AIService until the MCP endpoint is fully verified.

With the local spine verified and running cleanly, the umbrella repository declared v1.0.0. What had been a loose collection of distinct microservices now boots and operates as an integrated system.

Lessons learned

  • Default POSIX container paths in Go tools will fail path confinement on Windows. Defaulting directory configurations to "/workspace" or similar root paths violates filepath.IsAbs checks under Windows. Host-level launcher scripts must inject explicit absolute platform paths into environment variables.
  • Fail loudly when an upstream capability source is unreachable on startup. Allowing a dependent service to start against an unready tool registry and fall back to cached or synthesized definitions hides integration failures. The bootstrap script should verify the upstream port is listening and abort immediately if it is not.
  • State-aware stop scripts must only shut down processes they actively launched. Teardown automation should record the specific process IDs and container names it instantiated. Indiscriminately stopping services by port or name risks killing preexisting databases or background processes belonging to other tasks.