# Briney Codebox Python Init

> Python Project Initializer

- Skill: `tomevault-io/briney-codebox-python-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/briney-codebox-python-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/briney-codebox-python-init/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/briney-codebox-python-init

---


# Python Project Initializer

Scaffold a new Python project using modern conventions. The output is a ready-to-use
repository with a `pyproject.toml`-based build, src layout, dev tooling, and
pre-configured instructions for coding agents.

## What Gets Created

```
<project-name>/
  src/
    <package_name>/
      __init__.py
      py.typed
  tests/
    __init__.py
    test_placeholder.py
  .github/
    workflows/
      ci.yaml
  pyproject.toml
  README.md
  LICENSE
  .gitignore
  .python-version
  CLAUDE.md
  AGENTS.md
```

## Step-by-Step

### 1. Gather Information

You need at minimum:
- **Project name** (kebab-case, used for the repo directory and package distribution name)
- **Package name** (snake_case, used for the importable Python package — default: project name with hyphens replaced by underscores)
- **One-line description**
- **Python version** (default: `3.11`; prefer 3.11+ for modern typing syntax)

Optional:
- License (default: MIT)
- Initial dependencies
- Whether it's a CLI tool (adds a `[project.scripts]` entry)
- Author name and email

### 2. Create the Project

Read the templates in `templates/` and references in `references/` for content.
Adapt templates based on user answers from step 1.

Key files and their purposes:

#### pyproject.toml

Refer to `references/pyproject-guide.md` for the full annotated example. Key points:
- Use `[build-system]` with `hatchling` (simple, standards-compliant, no setup.py needed)
- Pin Python version with `requires-python`
- Define `[project.optional-dependencies]` for dev/test/docs extras
- Configure all tools (ruff, pytest, mypy) in pyproject.toml — no separate config files

#### CLAUDE.md

This file gives Claude Code project-specific context. Start with the template in
`templates/CLAUDE.md.template`, which includes:
- Build and test commands
- Project structure orientation
- Code style preferences
- Common workflows

The user should update this as the project evolves.

#### AGENTS.md

This file gives broader agent instructions (not Claude-specific). Start with the
template in `templates/AGENTS.md.template`, which includes:
- Architecture overview placeholder
- Contribution conventions
- Testing expectations
- What not to do

#### Github workflows

By default, we want two GitHub workflows at package initialization: `ci.yaml` and 
`python-publish.yaml`. Use the templates in `templates/` as a starting point, and 
modify as needed.

### 3. Initialize Git and Install

```bash
cd <project-name>
git init
git add -A
git commit -m "Initial project scaffold"

# Create a virtual environment and install in editable mode
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### 4. Create Notebook Entry

If the lab notebook is set up at `~/codebox/notebook/`, create a project entry:

```bash
mkdir -p ~/codebox/notebook/projects/<project-name>/sessions
```

Write an initial STATUS.md and add the project to PROJECTS.md.

### 5. Verify

Run the following to confirm everything works:

```bash
python -c "import <package_name>; print(<package_name>.__version__)"
pytest
ruff check src/
```

## Conventions

- **Always use src layout**. It prevents accidental imports from the working directory.
- **Always include `py.typed`**. Signals PEP 561 compliance for downstream type checkers.
- **No setup.py, setup.cfg, or requirements.txt**. Everything lives in `pyproject.toml`.
- **Ruff for linting and formatting**. Replaces black, isort, flake8, and pyflakes.
- **Pytest for testing**. Configured in pyproject.toml, not pytest.ini or conftest.py (conftest.py is fine for fixtures, just not config).

---
> Source: [briney/codebox](https://github.com/briney/codebox) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->