Wire Shared Package

Wire Shared Package

Wire a shared Python package as an editable local dependency across multiple research projects. Handles pyproject.toml creation, CLAUDE.md documentation, and Atlas infrastructure tracking.

When to Use

• A shared package exists and needs to be wired into downstream projects
• "Add collusion-sim as a dependency to these projects"
• "Wire up the shared package"
• "Set up cross-project dependency"
• After creating a shared package with computational-experiments scaffold mode

Phase 1: Discover

1. Identify the shared package:

   • Read its pyproject.toml to get name, version, and what it provides
   • Read its CLAUDE.md or README.md for module inventory
   • Confirm it installs cleanly: uv pip install -e ".[dev]"

2. Identify downstream projects:

   • If not specified, ask which projects should depend on this package
   • For each project, classify the dependency tier:

3. Check prerequisites for each downstream project:
   • Does it have a pyproject.toml? (Tier 1 projects need one)
   • Does it have a CLAUDE.md? (all tiers need one)
   • Does it have an Atlas topic file? (locate via project_path in frontmatter)

Phase 2: Wire Tier 1 Projects

For each Tier 1 downstream project:

2a. Create or update pyproject.toml

If no pyproject.toml exists, create one:

[project]
name = "{project-kebab-name}"
version = "0.1.0"
description = "{one-line from CLAUDE.md}"
requires-python = ">=3.11"
dependencies = [
    "{shared-package-name}",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.3",
]

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

[tool.hatch.build.targets.wheel]
packages = ["src/{project_underscored_name}"]

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

[tool.uv.sources]
{shared-package-name} = { path = "{relative-path-to-package}", editable = true }

If pyproject.toml already exists, add the dependency to [project] dependencies and add the [tool.uv.sources] entry.

Key: The [tool.uv.sources] section tells uv to resolve the package from a local path instead of PyPI. The relative path must be correct from the downstream project to the shared package (typically ../package-name).

2b. Update CLAUDE.md

Add a "Shared Package Dependency" section under ## Setup:

### Shared Package Dependency
- **`{package-name}`** installed as editable dependency from `{relative-path}/`
- Provides: {list key modules this project uses}
- Install: `uv pip install -e ".[dev]"` (resolves {package-name} via `[tool.uv.sources]`)
- Project-specific code goes in `src/{project_name}/` — shared simulation code stays in {package-name}

2c. Verify install

cd "{project-path}" && uv pip install -e ".[dev]"

Then verify imports:

uv run python -c "from {package_module} import {key_class}; print('OK')"

Phase 3: Document Tier 2 Projects

For each Tier 2 downstream project, add to CLAUDE.md under ## Setup:

### Shared Package Dependency (Tier 2)
- **`{package-name}`** at `{relative-path}/` — provides {what this project will use}
- When code work begins, add `{package-name}` as editable dependency via `[tool.uv.sources]` in `pyproject.toml`
- This project will extend the framework with {project-specific extensions}

No pyproject.toml changes — the dependency is documented but not yet wired.

Phase 4: Track in Atlas

For each downstream project that has an Atlas topic file, add a ## Shared Infrastructure section between the Description and Key References sections:

## Shared Infrastructure

- **`{package-name}`** (Tier {N} — {direct reuse|partial reuse|pattern only}): {what components are used}
- Location: `{theme}/{package-dir}/`
{if Tier 1:}
- Install: editable dependency via `pyproject.toml` `[tool.uv.sources]`

Placement: After ## Description (or ## Portfolio Bridge if present), before ## Key References.

Finding the right topic file: Search Atlas by project_path frontmatter field:

grep -rl "project_path.*{project-folder}" ~/vault/atlas/

Phase 5: Update Shared Package Documentation

If the shared package has a CLAUDE.md or README.md, update its downstream project table to reflect all wired projects:

## Downstream Projects

| Project | Tier | Uses |
|---------|------|------|
| {Project Name} | {1/2/3} | {components used} |

Anti-Patterns

• Never wire a dependency that doesn't install cleanly. Verify uv pip install -e . on the shared package first.
• Never create pyproject.toml for Tier 2 projects. They don't have active code yet — premature wiring creates broken installs.
• Never use absolute paths in [tool.uv.sources]. Always use relative paths from the downstream project.
• Never skip the Atlas update. The whole point is cross-project tracking.
• Never put the shared package's code in a downstream project. Shared code stays in the shared package; project-specific code goes in the project's own src/.

Verification

After completing all phases:

1. All Tier 1 projects install without errors
2. Key imports from the shared package work in each Tier 1 project
3. Every downstream project's CLAUDE.md mentions the dependency
4. Every downstream project's Atlas topic has a ## Shared Infrastructure section
5. The shared package's documentation lists all downstream projects

Quick check: grep -rl "{package-name}" ~/vault/atlas/ should return all expected topic files.

Defaults