moai/.planning/phases/01-foundation/01-01-PLAN.md

phase	plan	type
01-foundation	01	execute

Set up project scaffolding with pyproject.toml, ruff, pre-commit, and src layout.

Purpose: Establish consistent tooling from day one—linting, formatting, testing infrastructure. Output: Working Python project structure with uv sync installing all deps, ruff/pre-commit configured.

<execution_context> ~/.claude/get-shit-done/workflows/execute-phase.md ~/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @SPEC.md @CLAUDE.md

Constraints from PROJECT.md:

• Python 3.11+
• ruff (line length 100)
• pytest, 80%+ coverage on core logic
• Type hints required on public functions
• Docstrings required on modules and classes
• Dependencies unpinned unless security required

Task 1: Create pyproject.toml with dependencies and tool config pyproject.toml Create pyproject.toml with:

[project] section:

• name = "moai"
• version = "0.1.0"
• description = "Multi-AI collaborative brainstorming platform"
• requires-python = ">=3.11"
• dependencies: python-telegram-bot, sqlalchemy, httpx, aiosqlite (for async SQLite)

[project.optional-dependencies]:

• dev: pytest, pytest-cov, pytest-asyncio, ruff, pre-commit

[tool.ruff] section:

• line-length = 100
• target-version = "py311"

[tool.ruff.lint]:

• select = ["E", "F", "I", "N", "W", "UP"]

[tool.pytest.ini_options]:

• testpaths = ["tests"]
• asyncio_mode = "auto"

[build-system]:

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

Use hatchling as build backend (modern, works well with uv). Do NOT pin dependency versions. uv sync completes without errors pyproject.toml valid, all dependencies installable

Task 2: Create pre-commit configuration .pre-commit-config.yaml Create .pre-commit-config.yaml with:

Hooks:

1. ruff (linting): repo = https://github.com/astral-sh/ruff-pre-commit, hooks = [ruff, ruff-format]
2. Standard pre-commit hooks: trailing-whitespace, end-of-file-fixer, check-yaml

Use latest rev for ruff-pre-commit (check GitHub for current version, approximately v0.11.x).

Do NOT add pytest hook—running tests on every commit is too slow. Tests run manually or in CI. pre-commit install && pre-commit run --all-files passes Pre-commit hooks installed and passing

Task 3: Create src layout and package structure src/moai/__init__.py, src/moai/bot/__init__.py, src/moai/bot/handlers/__init__.py, src/moai/core/__init__.py, tests/__init__.py Create directory structure per SPEC.md:

src/moai/init.py - Package marker with version = "0.1.0" src/moai/bot/init.py - Bot subpackage marker (docstring: "Telegram bot handlers and entry point") src/moai/bot/handlers/init.py - Handlers subpackage marker src/moai/core/init.py - Core subpackage marker (docstring: "Core business logic, models, and services") tests/init.py - Test package marker

Each init.py should have a module docstring describing its purpose. Use triple-quoted docstrings at the top of each file. python -c "import moai; print(moai.version)" prints "0.1.0" Package importable, structure matches SPEC.md

Before declaring plan complete: - [ ] `uv sync` succeeds without errors - [ ] `pre-commit run --all-files` passes - [ ] `python -c "import moai"` succeeds - [ ] `ruff check src tests` passes - [ ] Directory structure matches SPEC.md file structure

<success_criteria>

• All tasks completed
• All verification checks pass
• No linting errors
• Package installable and importable </success_criteria>

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