Decisions

Package manager: uv — fast, modern, native workspace support
Linter/formatter: ruff — replaces black + flake8 in one tool
Type checker: mypy (strict) — catches bugs early
Build backend: hatchling — lightweight, works well with uv
Layout: flat monorepo (src/common/common/) — avoids nested src layers
Python version: 3.12+ — latest stable, modern syntax
Initial packages: only common — others added when features need them
Deferred: CLI framework choice (Phase 2)

User Tasks

FR-009: Python Project Scaffold

Summary

Set up src/ as a proper Python monorepo with package structure, dependency management, and dev tooling.

Problem / Motivation

CLAUDE.md specifies src/ as the code directory, but it’s empty. No pyproject.toml, no package structure, no virtual environment. Every future FR that involves code (FR-020, FR-015, FR-043, etc.) is blocked by this.

Proposed Solution

Modern Python monorepo using uv workspaces, with a shared common package as the foundation.

Open Questions

No open questions for Phase 1.

Phase Overview

Phase	Description	Status
Phase 1	Project scaffold + tooling	awaiting approval
Phase 2	Capability tests from completed FRs	—
Phase 3	CLI entry point (uv workspace patterns)	—

Phase 1: Project Scaffold — awaiting approval

Goal: Create the minimal Python monorepo structure with dev tooling.

Proposed file structure

Opus/
├── .python-version              # "3.12"
├── pyproject.toml               # Workspace root + ruff/mypy/pytest config
├── DEVELOPING.md                # Dev setup instructions
├── src/common/
│   ├── pyproject.toml           # Package config (hatchling, pydantic dep)
│   └── common/
│       ├── __init__.py
│       ├── py.typed             # PEP 561 marker
│       ├── config.py            # OpusConfig dataclass from env vars
│       ├── logging.py           # setup_logging() helper
│       ├── vault.py             # vault_path(), read/list vault files
│       └── types.py             # FeatureStatus StrEnum
└── tests/
    ├── conftest.py              # tmp_vault fixture
    └── common/
        ├── test_config.py
        └── test_vault.py

Key design notes

No __init__.py in test dirs — avoids shadowing the installed common package
dependency-groups.dev instead of deprecated tool.uv.dev-dependencies
Root pyproject.toml depends on common via workspace source
.gitignore additions: dist/, build/, .mypy_cache/, .pytest_cache/, .ruff_cache/, .coverage, htmlcov/
CLAUDE.md project tree updated to reflect new structure

Coding conventions

.env parsing: Read secrets into local variables via a dedicated parser, never pollute process.env — prevents leaking secrets to child processes
Path resolution: Use fileURLToPath(import.meta.url) instead of new URL(import.meta.url).pathname — the latter breaks on paths with spaces
Reference: ClaudeClaw Rebuild Prompt for implementation patterns

Phase 2: Capability Tests from Completed FRs —

Goal: Convert tests from completed FRs into pytest scripts so they run as part of the test suite.

File / Feature	Details	Owner	Status
Test conversion	For each done FR, translate its Test section into a pytest script	opus	—
Test location	`tests/capabilities/`	opus	—
CI integration	`uv run pytest tests/capabilities/` runs all capability tests	opus	—

Phase 3: CLI Entry Point — —

Goal: Create a CLI entry point using uv workspace patterns.

File / Feature	Details	Owner	Status
CLI package	`src/cli/` as separate workspace member	opus	—
CLI framework	Click or argparse (to be decided)	mv	—
Basic commands	`opus status`, `opus feature list` as proof-of-concept	opus	—

Acceptance Criteria

uv sync --group dev installs all dependencies
uv run ruff check . passes clean
uv run ruff format --check . passes clean
uv run mypy src/ passes clean (strict mode)
uv run pytest passes with all tests green
from common.config import OpusConfig works
from common.vault import vault_path works

Prerequisites / Gap Analysis

Requirements

Requirement	Description
REQ-1	Python 3.12+ installed on system
REQ-2	uv installed (`pip install uv` or standalone)

Current State

Component	Status	Details
`src/` directory	—	Empty, only .gitkeep
`pyproject.toml`	—	Does not exist

Test

Manual tests

Test	Expected	Owner	Actual	Last
`uv sync --group dev`	Installs without errors	opus	pending	-
`uv run ruff check .`	Clean, no warnings	opus	pending	-
`uv run ruff format --check .`	Clean	opus	pending	-
`uv run mypy src/`	Clean, strict mode	opus	pending	-
`uv run pytest`	All tests pass	opus	pending	-

AI-verified tests

Scenario	Expected behavior	Verification method
…	…	…

E2E tests

Scenario	Assertion
…	…

Integration tests

Component	Coverage
…	…

Unit tests

Component	Tests	Coverage
…	…	…

History

Date	Event	Details
2026-02-27	Created
2026-02-28	Reformatted	Aligned to feature-request template
2026-02-28	Design documented	All Phase 1 decisions settled, file structure proposed

References

FR-010 (Testing Infrastructure) — depends on this scaffold
FR-015 (Secrets & Environment Management) — needs pyproject.toml
FR-028 (Feature Workflow Automation) — needs Python package

Opus Vault

Explorer

Python Project Scaffold