Initialize complete Python project with comprehensive documentation, development environment, and tooling. Use when creating a new Python project from scratch.
/plugin marketplace add pborenstein/plinth/plugin install pborenstein-plinth@pborenstein/plinthThis skill is limited to using the following tools:
templates/CLAUDE.md.templatetemplates/README.md.templatetemplates/pyproject.toml.templateInitialize a complete Python project with comprehensive documentation, development environment, and tooling.
Documentation:
README.md - Project overview and visionCLAUDE.md - Development guide for AI sessionsdocs/CONTEXT.md - Current session state (hot state)docs/IMPLEMENTATION.md - Phase-based implementation plandocs/DECISIONS.md - Architectural decision registrydocs/chronicles/ - Directory for phase chronicle filesPython Setup:
pyproject.toml - uv-based dependency management with dev tools.gitignore - Python-specific gitignorePackage Structure:
{package_name}/ - Main package directory{package_name}/cli.py - CLI entry point placeholdertests/ - Test directoryWorkflow:
/plinth:session-pickup and /plinth:session-wrapup)Ask the user for the following (use AskUserQuestion if needed):
Required:
PROJECT_NAME - Display name (e.g., "Temoa", "Apantli")
PACKAGE_NAME - Python package name (e.g., "temoa", "apantli")
DESCRIPTION - One-sentence project description
Optional (with defaults):
PYTHON_VERSION - Default: ">=3.11"
VERSION - Default: "0.1.0"
Derived:
Create the project directory and subdirectories:
mkdir -p {PROJECT_NAME}
mkdir -p {PROJECT_NAME}/{PACKAGE_NAME}
mkdir -p {PROJECT_NAME}/tests
mkdir -p {PROJECT_NAME}/docs
mkdir -p {PROJECT_NAME}/docs/chronicles
For each template file in skills/python-project-init/templates/:
{{PROJECT_NAME}} → PROJECT_NAME{{PACKAGE_NAME}} → PACKAGE_NAME{{DESCRIPTION}} → DESCRIPTION{{PYTHON_VERSION}} → PYTHON_VERSION{{VERSION}} → VERSIONTemplate mapping:
| Template | Target Location |
|---|---|
pyproject.toml.template | {PROJECT_NAME}/pyproject.toml |
README.md.template | {PROJECT_NAME}/README.md |
CLAUDE.md.template | {PROJECT_NAME}/CLAUDE.md |
.gitignore.template | {PROJECT_NAME}/.gitignore |
Create minimal Python package structure:
{PROJECT_NAME}/{PACKAGE_NAME}/init.py:
"""{{PROJECT_NAME}} - {{DESCRIPTION}}"""
__version__ = "{{VERSION}}"
{PROJECT_NAME}/{PACKAGE_NAME}/cli.py:
"""Command-line interface for {{PROJECT_NAME}}."""
import argparse
from . import __version__
def main():
"""Main entry point for the CLI."""
parser = argparse.ArgumentParser(
prog="{{PACKAGE_NAME}}",
description="{{DESCRIPTION}}",
)
parser.add_argument(
"--version",
action="version",
version=f"{{PROJECT_NAME}} {__version__}",
)
args = parser.parse_args()
# Add your CLI logic here
print(f"{{PROJECT_NAME}} v{__version__}")
print("Ready to go!")
if __name__ == "__main__":
main()
{PROJECT_NAME}/tests/init.py:
"""Test suite for {{PROJECT_NAME}}."""
{PROJECT_NAME}/tests/test_basic.py:
"""Basic tests for {{PROJECT_NAME}}."""
from {{PACKAGE_NAME}} import __version__
def test_version():
"""Test version is defined."""
assert __version__ is not None
assert isinstance(__version__, str)
Use the project-tracking skill to create comprehensive documentation:
Invoke the project-tracking skill for a new project:
- Project name: {PROJECT_NAME}
- Current phase: Phase 0 - Research & Design
- Initial description: {DESCRIPTION}
This will create:
docs/CONTEXT.md with current session statedocs/IMPLEMENTATION.md with Phase 0 setupdocs/DECISIONS.md with decision tracking registrydocs/chronicles/phase-0-foundation.md with initial entryAsk the user if they want to initialize a git repository:
cd {PROJECT_NAME}
git init
git add .
git commit -m "$(cat <<'EOF'
docs: establish project infrastructure and comprehensive documentation
Set up {PROJECT_NAME} with comprehensive documentation following proven
patterns from plinth project templates. Established tech stack and
development workflow.
Documentation Structure:
- README.md: Project overview and vision
- CLAUDE.md: Development guide for AI sessions
- docs/CONTEXT.md: Current session state
- docs/IMPLEMENTATION.md: Phase-based implementation tracking
- docs/DECISIONS.md: Architectural decision registry
- pyproject.toml: Python setup with uv
Project Structure:
- {PACKAGE_NAME}/: Main Python package
- tests/: Test suite with pytest
- Development tools: mypy, ruff, pytest
Current Status: Phase 0 (Research & Design)
Next Step: Define core features and begin implementation planning
EOF
)"
Ask the user if they want to set up the development environment now:
cd {PROJECT_NAME}
uv sync
uv run {PACKAGE_NAME} --version
uv run pytest
This will:
.venv/ directoryuv.lock fileProvide verification commands and next steps to the user:
Verification:
cd {PROJECT_NAME}
# Verify structure
ls -la
ls -la {PACKAGE_NAME}
ls -la docs
# Verify CLI
uv run {PACKAGE_NAME} --version
# Run tests
uv run pytest
Next Steps:
README.md to add vision and feature detailsCLAUDE.md to add project-specific principlesdocs/IMPLEMENTATION.md Phase 0 with specific taskspyproject.toml as neededSession Management:
/plinth:session-pickup to resume work in next session/plinth:session-wrapup to document progress and commit changesBefore finishing, verify:
After completion, tell the user:
/plinth:session-pickup in next sessioncd {PROJECT_NAME} && uv sync && uv run {PACKAGE_NAME} --versionKeep it brief and technical. Focus on what they need to do next.
| Variable | Example | Description |
|---|---|---|
{{PROJECT_NAME}} | "Temoa" | Display name for documentation |
{{PACKAGE_NAME}} | "temoa" | Python package name (lowercase) |
{{DESCRIPTION}} | "Language learning platform" | One-line description |
{{PYTHON_VERSION}} | ">=3.11" | Python version requirement |
{{VERSION}} | "0.1.0" | Initial project version |