---
phase: 01-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - pyproject.toml
  - .python-version
  - vmcluster_mcp/__init__.py
  - vmcluster_mcp/topology/__init__.py
  - vmcluster_mcp/cluster/__init__.py
  - vmcluster_mcp/snapshot/__init__.py
  - vmcluster_mcp/exec/__init__.py
  - vmcluster_mcp/artifact/__init__.py
  - vmcluster_mcp/observe/__init__.py
  - vmcluster_mcp/net/__init__.py
  - tests/__init__.py
  - tests/conftest.py
autonomous: true
requirements:
  - FOUND-01

must_haves:
  truths:
    - "uv sync succeeds without errors"
    - "vmcluster_mcp is importable as a Python package"
    - "All 7 subpackage directories exist with __init__.py files"
    - "ruff check passes on the project"
  artifacts:
    - path: "pyproject.toml"
      provides: "Project metadata and all dependency declarations"
      contains: "mcp"
    - path: "vmcluster_mcp/__init__.py"
      provides: "Root package marker"
  key_links: []
---

<objective>
Create the vmcluster-mcp Python project structure with all dependencies declared, build tooling configured, and the complete module directory tree established per the design doc section 2.5.

Purpose: Every subsequent plan depends on an installable Python project with the correct dependency set and module layout. This must land first.
Output: Installable Python package with 7 subpackage directories matching the design doc.
</objective>

<execution_context>
@~/.copilot/get-shit-done/workflows/execute-plan.md
@~/.copilot/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/research/STACK.md
@docs/vmcluster-mcp-design.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create project scaffold with pyproject.toml, module directories, and test infrastructure</name>
  <files>pyproject.toml, .python-version, vmcluster_mcp/__init__.py, vmcluster_mcp/topology/__init__.py, vmcluster_mcp/cluster/__init__.py, vmcluster_mcp/snapshot/__init__.py, vmcluster_mcp/exec/__init__.py, vmcluster_mcp/artifact/__init__.py, vmcluster_mcp/observe/__init__.py, vmcluster_mcp/net/__init__.py, tests/__init__.py, tests/conftest.py</files>
  <read_first>
    - docs/vmcluster-mcp-design.md (section 2.5 for module structure, section 3.4 for dependency summary)
    - .planning/research/STACK.md (verified library versions and build tooling recommendations)
  </read_first>
  <action>
Create `pyproject.toml` with this exact content:

```toml
[project]
name = "vmcluster-mcp"
version = "0.1.0"
description = "MCP server for autonomous multi-VM cluster orchestration on libvirt/QEMU"
requires-python = ">=3.11"
dependencies = [
    "mcp[cli]>=1.26.0",
    "pydantic>=2.12.5",
    "asyncssh>=2.22.0",
    "libvirt-python>=12.1.0",
    "PyYAML>=6.0.3",
]

[dependency-groups]
dev = [
    "pytest>=9.0.2",
    "pytest-asyncio>=1.3.0",
    "pytest-mock>=3.15.1",
    "ruff>=0.15.7",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 120
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
```

Create `.python-version` containing `3.11`.

Create the directory tree matching design doc section 2.5:

```
vmcluster_mcp/
├── __init__.py           # empty
├── topology/
│   └── __init__.py       # empty
├── cluster/
│   └── __init__.py       # empty
├── snapshot/
│   └── __init__.py       # empty
├── exec/
│   └── __init__.py       # empty
├── artifact/
│   └── __init__.py       # empty
├── observe/
│   └── __init__.py       # empty
└── net/
    └── __init__.py       # empty

tests/
├── __init__.py           # empty
└── conftest.py           # empty file (placeholder for shared fixtures)
```

All `__init__.py` files are empty. `tests/conftest.py` is an empty file.

Run `uv sync` to install all dependencies and verify the lockfile generates successfully.

**Note:** `libvirt-python` requires system `libvirt-dev` and `python3-dev` packages. If `uv sync` fails on `libvirt-python`, install system deps first: `sudo apt-get install -y libvirt-dev python3-dev pkg-config`. If system deps are unavailable, exclude `libvirt-python` from sync for now and add `--no-build-isolation` or mark it as platform-conditional; this does NOT block Phase 1 since no Phase 1 code imports libvirt.
  </action>
  <verify>
    <automated>uv sync 2>&1 || echo "uv sync issue - check libvirt-dev"; uv run python -c "import vmcluster_mcp; import vmcluster_mcp.topology; import vmcluster_mcp.cluster; import vmcluster_mcp.exec; import vmcluster_mcp.artifact; import vmcluster_mcp.observe; import vmcluster_mcp.net" && echo "ALL IMPORTS OK"; uv run ruff check . && echo "RUFF OK"</automated>
  </verify>
  <acceptance_criteria>
    - pyproject.toml contains `name = "vmcluster-mcp"`
    - pyproject.toml contains `"mcp[cli]>=1.26.0"` in dependencies
    - pyproject.toml contains `"pydantic>=2.12.5"` in dependencies
    - pyproject.toml contains `"asyncssh>=2.22.0"` in dependencies
    - pyproject.toml contains `"PyYAML>=6.0.3"` in dependencies
    - pyproject.toml contains `asyncio_mode = "auto"` in pytest config
    - pyproject.toml contains `target-version = "py311"` in ruff config
    - vmcluster_mcp/__init__.py exists
    - vmcluster_mcp/topology/__init__.py exists
    - vmcluster_mcp/cluster/__init__.py exists
    - vmcluster_mcp/snapshot/__init__.py exists
    - vmcluster_mcp/exec/__init__.py exists
    - vmcluster_mcp/artifact/__init__.py exists
    - vmcluster_mcp/observe/__init__.py exists
    - vmcluster_mcp/net/__init__.py exists
    - tests/__init__.py exists
    - tests/conftest.py exists
    - `uv run python -c "import vmcluster_mcp"` exits 0
  </acceptance_criteria>
  <done>Project is installable via uv, importable as `vmcluster_mcp`, all 7 subpackage directories from design doc section 2.5 exist with __init__.py files, and ruff/pytest tooling is configured.</done>
</task>

</tasks>

<verification>
- `uv sync` completes successfully (or with documented libvirt-python workaround)
- All subpackage imports succeed
- `ruff check .` passes
- `uv run pytest` exits 0 (no tests yet, but no collection errors)
</verification>

<success_criteria>
The vmcluster-mcp project is a valid, installable Python package with all declared dependencies, the complete module directory tree from the design doc, and configured build/lint/test tooling.
</success_criteria>

<output>
After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
</output>
