---
phase: 05-mvp-deployment
plan: 04
subsystem: infra
tags: [docker-compose, matrix, deployment, agents, docs]
requires:
  - phase: 05-03
    provides: "Shared /agents attachment contract and path normalization for Matrix runtime"
provides:
  - "docker-compose.prod.yml bot-only deployment handoff artifact"
  - "docker-compose.fullstack.yml internal E2E harness with health-gated platform-agent startup"
  - "README and deploy architecture docs aligned to the split compose contract"
affects: [mvp-deployment, operator-handoff, internal-e2e]
tech-stack:
  added: [Docker Compose]
  patterns: [split-compose-by-operational-intent, shared-agents-volume-contract]
key-files:
  created: [docker-compose.prod.yml, docker-compose.fullstack.yml]
  modified: [.env.example, README.md, docs/deploy-architecture.md]
key-decisions:
  - "Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification."
  - "Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same volume."
patterns-established:
  - "Production operators use docker-compose.prod.yml and provide an external AGENT_BASE_URL."
  - "Internal verification uses docker-compose.fullstack.yml with service_healthy gating instead of sleep-based startup."
requirements-completed: [PH05-05]
duration: 3 min
completed: 2026-04-27
---

# Phase 05 Plan 04: Split deployment artifacts Summary

**Bot-only production compose handoff plus a separate health-gated full-stack harness aligned to the shared `/agents` volume contract**

## Performance

- **Duration:** 3 min
- **Started:** 2026-04-27T22:12:42Z
- **Completed:** 2026-04-27T22:16:09Z
- **Tasks:** 2
- **Files modified:** 5

## Accomplishments
- Added `docker-compose.prod.yml` as the operator-facing bot-only runtime artifact.
- Added `docker-compose.fullstack.yml` for internal E2E runs with `platform-agent` health-gated startup.
- Updated env and deployment docs so `/agents` and the split compose flow are explicit without relying on the old root compose file.

## Task Commits

Each task was committed atomically:

1. **Task 1: Create split prod and fullstack compose artifacts** - `df6d8bf` (feat)
2. **Task 2: Update deployment docs and operator guidance for the split artifacts** - `22a3a2b` (docs)

**Plan metadata:** pending final docs commit after state updates

## Files Created/Modified
- `docker-compose.prod.yml` - bot-only deployment handoff with `/agents` volume contract
- `docker-compose.fullstack.yml` - internal harness extending the bot service and adding health-checked `platform-agent`
- `.env.example` - Phase 05 runtime variables for prod handoff and internal full-stack defaults
- `README.md` - operator-facing instructions for choosing the correct compose artifact
- `docs/deploy-architecture.md` - deployment topology and shared-volume guidance aligned to the split artifacts

## Decisions Made
- Split deployment packaging by operational intent instead of overloading one compose file for both prod handoff and internal testing.
- Kept the bot’s absolute shared path rooted at `/agents` in docs and env examples while letting the internal `platform-agent` consume the same named volume at `/workspace`.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

- The docs verification grep treated `deploy` inside the filename `docs/deploy-architecture.md` as a false positive when root compose was still named explicitly. The fix was to remove the literal root compose filename from deploy-path wording while keeping the deprecation clear.

## User Setup Required

None - no external service configuration required beyond populating `.env` from `.env.example`.

## Next Phase Readiness

- Operators now have a bot-only compose artifact for handoff, and developers have a separate internal E2E harness.
- Remaining Phase 05 work can rely on the split runtime contract without reinterpreting deployment docs.

## Self-Check: PASSED

- Summary file exists at `.planning/phases/05-mvp-deployment/05-04-SUMMARY.md`
- Commit `df6d8bf` found in git history
- Commit `22a3a2b` found in git history

---
*Phase: 05-mvp-deployment*
*Completed: 2026-04-27*