scaffold

Scaffold

Creates well-formed batterie-de-savoir Python repos from a checklist derived from building 10+ repos. Every new repo starts at the same baseline — git, hatchling, src layout, tests, CLAUDE.md, bon, GitHub remote.

Iron Law: Structure is deterministic. Meaning is not. The init script creates the skeleton; you fill in the CLAUDE.md content that makes the repo navigable.

When to Use

• Creating a new Python package from scratch
• Promoting scratch/noodling code into a proper repo
• Extracting a module from an existing repo into its own package
• /close suggests this when detecting code in a non-repo directory

Boundaries

• Python repos only (TypeScript is a future extension)
• Does not create plugin structure (.claude-plugin/, skills/) — that's a different concern
• Does not handle monorepo setups

Workflow

Step 1: Interview

Determine the mode and gather inputs.

Ask the user:

1. What's the project name? (kebab-case, becomes the repo name)
2. One-line description?
3. What's the bon prefix? (3-4 lowercase letters)

Detect the mode:

• Greenfield — target directory is empty or doesn't exist
• Adopt — target directory has code but no .git/
• Extract — user mentions pulling code from another repo

For adopt, list existing files and confirm they'll be preserved (moved into src/<pkg>/). For extract, identify the source module and confirm what's moving.

Step 2: Plan

Show the user what will be created:

Scaffold plan for <name>:
  Mode: greenfield / adopt / extract
  Package: src/<pkg>/
  Bon prefix: <prefix>
  GitHub: spm1001/<name> (public)

  Files to create:
    pyproject.toml          — hatchling, src layout, pytest config
    src/<pkg>/__init__.py   — importlib.metadata version
    .gitignore              — Python standard
    tests/__init__.py       — empty
    tests/conftest.py       — stub
    CLAUDE.md               — [TODO] sections for you to fill
    .bon/                   — work tracker
    .bon/understanding.md   — seed

  [adopt only] Existing files to relocate:
    <list>

Confirm with user before proceeding.

Step 3: Execute

Greenfield:

uv run --script ${CLAUDE_SKILL_DIR}/scripts/init_repo.py \
  --name <name> --prefix <prefix> --description "<desc>"

Adopt:

1. Move existing code into src/<pkg>/ (preserve structure)
2. Run init_repo.py with --dir pointing to the working directory
   • The script will warn about non-empty directory — that's expected
3. Manually adjust if the script created files that conflict with existing ones

Extract:

1. Create target directory
2. Copy source module into src/<pkg>/
3. Run init_repo.py
4. Update source repo to remove extracted code and add dependency

Step 4: Fill CLAUDE.md

The init script leaves [TODO] markers. Replace each one with project-specific content:

Module Map — list every module under src/<pkg>/ with a one-line role description. Use a table:

| Module | Role |
|--------|------|
| `parsing` | JSONL loading, entry type classification |
| `content` | System tag stripping, assistant content extraction |

Key Conventions — document the things a future Claude needs to know:

• What dependencies are allowed (stdlib only? specific packages?)
• What patterns to follow (re-exports from __init__.py?)
• What NOT to "fix" (deliberate quirks)
• Quick commands beyond the standard ones

For adopt/extract mode, also note the origin of the code and any context about why it was extracted.

Step 5: Validate

uv run --script ${CLAUDE_SKILL_DIR}/scripts/validate_repo.py

Review the report. Fix any FAIL items. Re-run until all checks pass.

If validate_repo.py doesn't exist yet, manually verify:

• Git repo on main branch (not detached HEAD)
• .gitignore present with Python patterns
• pyproject.toml: hatchling backend, src layout, [dependency-groups] dev, pytest config
• src/<pkg>/__init__.py with __version__ via importlib.metadata
• tests/ with conftest.py
• CLAUDE.md present, no remaining [TODO] markers
• .bon/ initialized with correct prefix
• GitHub remote configured and pushed

The Checklist

Derived from cross-repo survey of 10 batterie repos (April 2026) and every mistake made building deglacer:

Item	Why
git init -b main	Never detached HEAD
.gitignore	Python bytecode, build artifacts, venv
pyproject.toml with hatchling	Single version source, src layout
[dependency-groups] dev	Separate dev deps from runtime
[tool.pytest.ini_options]	pythonpath = ["src"] avoids import errors
src/<pkg>/__init__.py	importlib.metadata version — no hardcoded version
tests/__init__.py + conftest.py	Test infrastructure ready from day one
CLAUDE.md	Orientation, quick commands, module map, conventions
bon init --prefix	Work tracker from the start
.bon/understanding.md	Knowledge accumulation seed
gh repo create	HTTPS remote, ready to push

Common Mistakes

Mistake	What Happens	Better
Hardcoded version in pyproject.toml	Dual-maintenance drift	importlib.metadata pattern
Missing pythonpath = ["src"] in pytest config	Import errors in tests	Always include it
No .gitignore	__pycache__ committed	Create before first commit
setuptools instead of hatchling	Inconsistent with suite	Hatchling everywhere
Flat layout instead of src/	Import confusion in tests	Always src/<pkg>/
Skipping bon init	No work tracker	Init with prefix immediately
CLAUDE.md with just the name	Useless orientation	Fill in module map and conventions

Integration

• Bon: Every scaffolded repo gets bon initialized. Actions filed here continue in the new repo.
• Skill-forge: If the new repo will have skills, use skill-forge after scaffold completes.
• /close: Can suggest scaffold when detecting code in a non-repo directory (bds-tipuji).