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:
- Path confinement on Windows:
MCPServerin 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, causingpathconfineto fail startup immediately. The launcher script now explicitly setsMCP_WORKSPACE_ROOTto the absolute Windows developer root. - Missing capability sidecar: Starting
MCPServerdirectly without settingMCP_CAPABILITY_SIDECARsilently downgraded all tools without an inline declaration toRequireApproval, causing test runs to behave unpredictably. - Hard dependency readiness gating: When
AIServicestarts up, its initial handshake fetches tool capabilities fromMCPServer. IfAIServicebooted beforeMCPServerwas actually listening on:8080, it fell back to stale in-memory config metadata. PR #42 added an activeTest-PortOpencheck, refusing to launchAIServiceuntil 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 violatesfilepath.IsAbschecks 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.