---
phase: 01-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- pyproject.toml
- src/skill_retriever/__init__.py
- src/skill_retriever/py.typed
- src/skill_retriever/config.py
- src/skill_retriever/entities/__init__.py
- src/skill_retriever/nodes/__init__.py
- src/skill_retriever/workflows/__init__.py
- src/skill_retriever/models/__init__.py
- src/skill_retriever/memory/__init__.py
- src/skill_retriever/mcp/__init__.py
- src/skill_retriever/utils/__init__.py
- tests/__init__.py
- tests/test_init.py
- .python-version
autonomous: true
must_haves:
truths:
- "`uv run pytest` executes with zero errors"
- "`from skill_retriever import __version__` returns '0.1.0'"
- "`uv run ruff check .` exits with zero warnings"
- "`uv run pyright` exits with zero errors"
- "EmbeddingConfig loads with model_name='BAAI/bge-small-en-v1.5' and dimensions=384"
artifacts:
- path: "pyproject.toml"
provides: "Project metadata, dependencies, tool config (ruff, pyright, pytest)"
contains: "[build-system]"
- path: "src/skill_retriever/__init__.py"
provides: "Package entry point with __version__"
contains: "importlib.metadata"
- path: "src/skill_retriever/config.py"
provides: "EmbeddingConfig Pydantic model with pinned defaults"
contains: "EMBEDDING_CONFIG"
- path: "tests/test_init.py"
provides: "Smoke tests for version import and config load"
contains: "test_version_importable"
key_links:
- from: "src/skill_retriever/__init__.py"
to: "pyproject.toml"
via: "importlib.metadata.version reads version from installed package metadata"
pattern: 'version\("skill-retriever"\)'
- from: "tests/test_init.py"
to: "src/skill_retriever/config.py"
via: "import and assert on EMBEDDING_CONFIG singleton"
pattern: "from skill_retriever.config import EMBEDDING_CONFIG"
---
<objective>
Scaffold the skill-retriever Python package with uv, configure all dev tools, pin the embedding model, and verify all four Phase 01 success criteria pass.
Purpose: Establish the foundation every subsequent phase builds on. Correct toolchain setup here prevents cascading issues across 6 phases.
Output: Importable package, passing tests, zero-warning linting/type-checking, pinned embedding config.
</objective>
<execution_context>
@C:\Users\33641\.claude/get-shit-done/workflows/execute-plan.md
@C:\Users\33641\.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-foundation/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Scaffold project and install dependencies</name>
<files>
pyproject.toml
.python-version
src/skill_retriever/__init__.py
src/skill_retriever/py.typed
src/skill_retriever/config.py
src/skill_retriever/entities/__init__.py
src/skill_retriever/nodes/__init__.py
src/skill_retriever/workflows/__init__.py
src/skill_retriever/models/__init__.py
src/skill_retriever/memory/__init__.py
src/skill_retriever/mcp/__init__.py
src/skill_retriever/utils/__init__.py
</files>
<action>
1. Run `uv init --lib skill-retriever` from the repo root. If the project already exists (pyproject.toml present), skip this step and work with the existing structure.
2. Replace the generated pyproject.toml with the complete version from RESEARCH.md:
- [project] with name="skill-retriever", version="0.1.0", requires-python=">=3.13"
- dependencies: fastembed>=0.7.4, pydantic>=2.12.5
- [dependency-groups] dev: pytest>=9.0.2, pytest-asyncio>=0.24, pytest-cov>=6.0, ruff>=0.14.14, pyright>=1.1.408
- [build-system] with uv_build>=0.9.28,<0.10.0
- [tool.ruff] target-version="py313", line-length=100, lint.select with E, F, W, I, N, UP, B, SIM, TCH, RUF
- [tool.ruff.lint.isort] known-first-party=["skill_retriever"]
- [tool.pyright] pythonVersion="3.13", typeCheckingMode="strict", reportMissingTypeStubs=false
- [tool.pytest.ini_options] asyncio_mode="auto", testpaths=["tests"]
3. Replace src/skill_retriever/__init__.py with:
```python
"""Skill Retriever: Graph-based MCP server for Claude Code component retrieval."""
from importlib.metadata import version
__version__ = version("skill-retriever")
```
4. Create src/skill_retriever/config.py with:
```python
"""Pinned embedding model configuration."""
from pydantic import BaseModel, Field
class EmbeddingConfig(BaseModel):
"""Pinned embedding model configuration."""
model_name: str = Field(default="BAAI/bge-small-en-v1.5")
dimensions: int = Field(default=384)
max_length: int = Field(default=512)
cache_dir: str | None = Field(default=None)
EMBEDDING_CONFIG = EmbeddingConfig()
```
5. Create empty __init__.py files in all Iusztin virtual layer subdirectories:
- src/skill_retriever/entities/__init__.py
- src/skill_retriever/nodes/__init__.py
- src/skill_retriever/workflows/__init__.py
- src/skill_retriever/models/__init__.py
- src/skill_retriever/memory/__init__.py
- src/skill_retriever/mcp/__init__.py
- src/skill_retriever/utils/__init__.py
Each file should contain only a docstring: `"""<Layer name> package."""`
6. Install all dependencies: `uv sync`
Do NOT add kuzu, fastmcp, or scikit-network. They are deferred to later phases.
Do NOT use pydantic-settings. Plain BaseModel is sufficient for Phase 01.
</action>
<verify>
```bash
uv run python -c "from skill_retriever import __version__; print(__version__)"
# Must print: 0.1.0
uv run python -c "from skill_retriever.config import EMBEDDING_CONFIG; print(EMBEDDING_CONFIG.model_name, EMBEDDING_CONFIG.dimensions)"
# Must print: BAAI/bge-small-en-v1.5 384
```
</verify>
<done>Package is importable, __version__ returns "0.1.0", EmbeddingConfig loads with pinned defaults, all subdirectories exist with __init__.py files.</done>
</task>
<task type="auto">
<name>Task 2: Add smoke tests and verify all success criteria</name>
<files>
tests/__init__.py
tests/test_init.py
</files>
<action>
1. Create tests/__init__.py (empty or with docstring).
2. Create tests/test_init.py with:
```python
"""Smoke tests for Phase 01 success criteria."""
def test_version_importable() -> None:
"""SC-1: from skill_retriever import __version__ works."""
from skill_retriever import __version__
assert isinstance(__version__, str)
assert __version__ == "0.1.0"
def test_embedding_config_loadable() -> None:
"""SC-4: Embedding model version is pinned and loadable."""
from skill_retriever.config import EMBEDDING_CONFIG
assert EMBEDDING_CONFIG.model_name == "BAAI/bge-small-en-v1.5"
assert EMBEDDING_CONFIG.dimensions == 384
assert EMBEDDING_CONFIG.max_length == 512
def test_subpackages_importable() -> None:
"""All Iusztin virtual layer subpackages are importable."""
import skill_retriever.entities
import skill_retriever.memory
import skill_retriever.mcp
import skill_retriever.models
import skill_retriever.nodes
import skill_retriever.utils
import skill_retriever.workflows
# If we got here without ImportError, all subpackages exist
assert True
```
3. Run the full verification suite:
```bash
uv run pytest tests/ -v
uv run ruff check .
uv run ruff format --check .
uv run pyright
```
4. Fix any issues found by ruff or pyright. Common fixes:
- If pyright complains about reportMissingTypeStubs for fastembed: already handled in config (set to false).
- If ruff finds import ordering issues: run `uv run ruff check --fix .`
- If ruff format differs: run `uv run ruff format .`
All four commands must exit with zero errors/warnings before this task is done.
</action>
<verify>
```bash
uv run pytest tests/ -v
# Must show 3 tests passed, 0 failed
uv run ruff check .
# Must show: All checks passed!
uv run pyright
# Must show: 0 errors, 0 warnings
uv run ruff format --check .
# Must show: X files already formatted (no changes needed)
```
</verify>
<done>All 3 smoke tests pass. Ruff lint and format report zero issues. Pyright strict mode reports zero errors. All four Phase 01 success criteria are met.</done>
</task>
</tasks>
<verification>
Run all four success criteria checks in sequence:
```bash
# SC-1: pytest passes
uv run pytest tests/ -v
# SC-2: version importable
uv run python -c "from skill_retriever import __version__; assert __version__ == '0.1.0'; print('OK')"
# SC-3: ruff + pyright clean
uv run ruff check . && uv run pyright
# SC-4: embedding config loadable
uv run python -c "from skill_retriever.config import EMBEDDING_CONFIG; assert EMBEDDING_CONFIG.model_name == 'BAAI/bge-small-en-v1.5'; print('OK')"
```
All four must pass with zero errors.
</verification>
<success_criteria>
1. `uv run pytest` runs 3 tests, all passing
2. `from skill_retriever import __version__` returns "0.1.0"
3. `uv run ruff check .` and `uv run pyright` both exit zero
4. `EMBEDDING_CONFIG.model_name == "BAAI/bge-small-en-v1.5"` and `EMBEDDING_CONFIG.dimensions == 384`
</success_criteria>
<output>
After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
</output>
