Fix template for library packages

.github/actions/setup/action.yml

@@ -8,7 +8,7 @@ runs:
       shell: bash
       run: |
         apt-get update -qq
-        apt-get install -y -qq ca-certificates curl git libvips python3 python3-tk python3-venv xvfb unar
+        apt-get install -y -qq ca-certificates curl git python3 python3-venv libatomic1 gnupg
 
     - name: Set up uv
       uses: astral-sh/setup-uv@v5
@@ -19,4 +19,4 @@ runs:
 
     - name: Sync dependencies
       shell: bash
-      run: source .venv/bin/activate && uv sync --all-extras
+      run: source .venv/bin/activate && uv sync --group dev

.github/workflows/ci.yml

@@ -1,3 +1,4 @@
+# TODO: After init, update CODECOV_TOKEN in GitHub repository secrets if using Codecov
 name: CI
 
 on:

AGENTS.md

@@ -1,26 +1,28 @@
 # Repository Guidelines
 
+> **⚠️ TEMPLATE FILE - This contains template-specific patterns. After initialization, update for your project's needs.**
+
 ## Project Structure & Module Organization
-The main application code lives in the `example_module` directory (which can be renamed via `make init`). The entrypoint is `main.py`. Tooling metadata (`pyproject.toml`, `uv.lock`) defines project dependencies. Expect any future modules (tests, components, helpers) to sit alongside these files unless a new package directory is created.
+The main application code lives in the `[[MODULE_NAME]]` directory (which can be renamed via `make init`). The default entrypoint is `main.py` for applications, but `make init` removes this file for library packages. Tooling metadata (`pyproject.toml`, `uv.lock`) defines project dependencies. Expect any future modules (tests, components, helpers) to sit alongside these files unless a new package directory is created. For applications, create an entrypoint file; for libraries, expose the package API through the module's `__init__.py`.
 
 ## Build, Test, and Development Commands
 - `make init NAME=your-project`: initialize the template with your project name (renames module and updates config).
 - `source .venv/bin/activate`: activate the virtual environment (do this once per session).
-- `uv sync --all-extras`: install dependencies via uv.
-- `python main.py`: run the main entrypoint.
+- `uv sync --group dev`: install dependencies via uv.
+- `python main.py`: run the main entrypoint (if present, for applications).
 - `pytest`: run tests.
 - `make pytest`: run the test suite.
 - `make lint`: run ruff.
 
 ## Getting Started
 When cloning this template for a new project:
 1. Run `make init NAME=your-project` to rename the module and update config
-2. Run `uv sync --all-extras` to install all dependencies
+2. Run `uv sync --group dev` to install all dependencies
 3. Run `source .venv/bin/activate` to activate the virtual environment
 4. Start building your project!
 
-## Git Worktrees (Parallel Work)
-Use git worktrees to work on multiple cards in parallel without branch conflicts:
+## Git Worktrees (Parallel Work - Optional)
+Git worktrees allow working on multiple cards in parallel without branch conflicts. This is an optional workflow pattern that many projects don't use.
 - Create a branch per card: `git switch -c card/short-slug`
 - Add a worktree: `git worktree add ../project-<slug> card/short-slug`
 - Work only in that worktree for the card; run tests there.
@@ -31,7 +33,7 @@ Use git worktrees to work on multiple cards in parallel without branch conflicts
 
 ## Test Coverage Requirements
 - Current target: 96% coverage threshold (configured in `pyproject.toml`)
-- Always run `pytest --cov=example_module --cov-report=term-missing` to check missing coverage
+- Always run `pytest --cov=[[MODULE_NAME]] --cov-report=term-missing` to check missing coverage
 - When touching logic or input handling, ensure tests are added to maintain coverage
 - Strategies for increasing coverage:
   - Add tests for remaining uncovered edge cases

CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Warning banners to README.md and AGENTS.md to clearly indicate template files
+- Post-initialization checklist section to README.md
+- Placeholder system using `[[MODULE_NAME]]` for easy replacement
+- POST_INIT_CHECKLIST.md with comprehensive post-init guidance
+- TEMPLATE_GUIDE.md explaining template purpose and usage
+- Improved `make init` output with summary of changes and next steps
+- Comment placeholder in CI workflow for Codecov token setup
+- Git worktrees section marked as optional in AGENTS.md
+
+### Changed
+
+- Replaced hardcoded "example_module" with `[[MODULE_NAME]]` placeholder in README.md
+- Updated CI badge URLs to use placeholders (YOUR_USERNAME/YOUR_REPO)
+- Enhanced `make init` target to provide detailed summary of automated changes
+- Improved documentation clarity with visual indicators (⚠️, ✅, 📋, etc.)
+
+### Improved
+
+- Template now provides clearer guidance on what gets automated vs manual
+- Better distinction between template-specific patterns and project-specific needs
+- More comprehensive documentation for new users
+- Enhanced visibility of post-initialization requirements
+
+## [0.1.0] - 2024-01-15
+
+### Added
+
+- Initial template release
+- Python 3.13 support
+- uv package manager integration
+- pytest with 96% minimum coverage
+- ruff for linting and formatting
+- pyright for type checking
+- Pre-commit hooks for code quality
+- GitHub Actions CI workflow
+- Make commands for common tasks
+- AGENTS.md for AI agent guidelines

Makefile

@@ -10,17 +10,45 @@ help:  ## Show this help message
 
 init:  ## Initialize project with new name (Usage: make init NAME=your-project)
 	@if [ -z "$(NAME)" ]; then echo "Usage: make init NAME=your-project"; exit 1; fi
-	@echo "Initializing project as $(NAME)..."
-	@sed -i.bak "s/python-starter-template/$(NAME)/g" pyproject.toml && rm pyproject.toml.bak
-	@sed -i.bak "s/example_module/$(NAME)/g" pyproject.toml && rm pyproject.toml.bak
+	$(eval PKG_DIR := $(subst -,_,$(NAME)))
+	@echo "Initializing project as $(NAME) (package dir: $(PKG_DIR))..."
+	@sed -i.bak 's/name = "python-starter-template"/name = "$(NAME)"/' pyproject.toml && rm pyproject.toml.bak
+	@sed -i.bak 's/example_module/$(PKG_DIR)/g' pyproject.toml && rm pyproject.toml.bak
+	@sed -i.bak 's/example_module/$(PKG_DIR)/g' .github/workflows/ci.yml && rm .github/workflows/ci.yml.bak
 	@if [ -d "example_module" ]; then \
-		echo "Renaming example_module to $(NAME)..."; \
-		mv example_module $(NAME); \
-		find . -type f -name "*.py" -exec sed -i.bak "s/from example_module/from $(NAME)/g" {} +; \
+		echo "Renaming example_module to $(PKG_DIR)..."; \
+		mv example_module $(PKG_DIR); \
+		find . -type f -name "*.py" -not -path "./.venv/*" -exec sed -i.bak "s/from example_module/from $(PKG_DIR)/g" {} +; \
+		find . -type f -name "*.py" -not -path "./.venv/*" -exec sed -i.bak "s/import example_module/import $(PKG_DIR)/g" {} +; \
 		find . -type f -name "*.py.bak" -delete; \
 	fi
-	@echo "Project initialized as $(NAME)"
-	@echo "Run 'uv sync --all-extras' to install dependencies"
+	@if [ -f "main.py" ]; then \
+		echo "Removing template main.py (library package)..."; \
+		rm main.py; \
+	fi
+	@echo ""
+	@echo "✅ Project initialized successfully!"
+	@echo ""
+	@echo "📋 SUMMARY OF CHANGES:"
+	@echo "  • Module renamed to: $(PKG_DIR)"
+	@echo "  • Package name in pyproject.toml: $(NAME)"
+	@echo "  • Python imports updated to use: $(PKG_DIR)"
+	@echo "  • CI workflow updated"
+	@echo "  • Template main.py removed (library package structure)"
+	@echo ""
+	@echo "⚠️  MANUAL UPDATES REQUIRED:"
+	@echo "  • Replace [[MODULE_NAME]] with $(PKG_DIR) in README.md and AGENTS.md"
+	@echo "  • Update CI badge URLs in README.md (YOUR_USERNAME/YOUR_REPO)"
+	@echo "  • Update project title, description, and features in README.md"
+	@echo "  • Review and customize AGENTS.md for your project"
+	@echo "  • See POST_INIT_CHECKLIST.md for complete details"
+	@echo ""
+	@echo "📦 NEXT STEPS:"
+	@echo "  1. Run: uv sync --all-extras"
+	@echo "  2. Run: source .venv/bin/activate"
+	@echo "  3. Run: make lint && make pytest"
+	@echo "  4. Follow POST_INIT_CHECKLIST.md for customization"
+	@echo ""
 
 lint:  ## Run code linting
 	bash scripts/lint.sh
@@ -38,7 +66,7 @@ pytest:  ## Run tests
 	pytest
 
 sync:  ## Install dependencies
-	uv sync --all-extras
+	uv sync --group dev
 
 venv:  ## Create virtual environment
 	uv venv

POST_INIT_CHECKLIST.md

@@ -0,0 +1,168 @@
+# Post-Initialization Checklist
+
+This checklist guides you through the manual steps needed after running `make init NAME=your-project` to customize your new project.
+
+## 🎯 Overview
+
+The `make init` command automates the following:
+- ✅ Renames the module directory from `example_module` to your project name (hyphenated names are normalized: my-project → my_project)
+- ✅ Updates `pyproject.toml` with your project name
+- ✅ Updates all Python imports to use the new module name
+- ✅ Updates CI workflow to use the new module name
+- ✅ Removes `main.py` (template uses a library package structure)
+
+However, some items require manual attention to ensure your project is properly configured.
+
+## 📋 Documentation Updates
+
+### README.md
+- [ ] **Update project title and description**
+  - Change "Python Starter Template" to your project name
+  - Update the description to reflect what your project does
+  - Add your project's specific features
+
+- [ ] **Replace `[[MODULE_NAME]]` references**
+  - Search for all instances of `[[MODULE_NAME]]`
+  - Replace with your actual module name (e.g., project name `my-project` becomes module directory `my_project`)
+
+- [ ] **Update CI badge URLs**
+  - Replace `YOUR_USERNAME` with your GitHub username
+  - Replace `YOUR_REPO` with your repository name
+  - Example: `https://github.com/johndoe/my-awesome-project/workflows/CI/badge.svg`
+
+- [ ] **Update features list**
+  - Remove or add features based on your project's capabilities
+  - Add specific libraries or frameworks your project uses
+
+- [ ] **Add usage examples**
+  - Replace template examples with your actual usage
+  - Add code snippets showing how to use your project
+
+- [ ] **Remove the warning banner**
+  - Delete the `⚠️ TEMPLATE FILE` banner at the top
+  - Remove the "📝 Post-Initialization Checklist" section
+
+### AGENTS.md
+- [ ] **Review and customize patterns**
+  - Update module organization to match your structure
+  - Add project-specific commands or workflows
+  - Remove git worktrees section if not using that workflow
+  - Update coverage commands to use your module name
+
+- [ ] **Remove the warning banner**
+  - Delete the `⚠️ TEMPLATE FILE` banner at the top
+
+## ⚙️ Configuration Updates
+
+### pyproject.toml
+- [ ] **Update project metadata**
+  ```toml
+  name = "your-project-name"
+  description = "Your project description"
+  authors = [{ name = "Your Name", email = "your.email@example.com" }]
+  ```
+
+- [ ] **Review dependencies**
+  - Remove unused template dependencies
+  - Add your project's specific dependencies
+  - Update dev dependencies as needed
+
+- [ ] **Update coverage configuration**
+  - Ensure `[[MODULE_NAME]]` is replaced with your actual module name
+  - Adjust coverage threshold if needed (default: 96%)
+
+### .github/workflows/ci.yml
+- [ ] **Review CI workflow**
+  - The workflow is automatically updated by `make init`
+  - Verify module name is correct in coverage commands
+  - Add additional jobs if needed (e.g., deployment, integration tests)
+
+## 🧹 Code Cleanup
+
+### Module Structure
+- [ ] **Review your module directory**
+  - Remove or modify `core.py` based on your needs
+  - Add new modules as needed
+  - Update `__init__.py` with your public API
+
+- [ ] **Update test files**
+  - Rename `test_example.py` to match your modules
+  - Remove template tests if not applicable
+  - Add tests for your actual functionality
+
+### main.py (if needed)
+- [ ] **Decide if you need an entrypoint**
+  - If creating a library: Keep removed (default behavior)
+  - If creating an application: Create `main.py` with your entry point
+  - Update `pyproject.toml` to include `[project.scripts]` if needed
+
+## 🧪 Testing Updates
+
+- [ ] **Update test configuration**
+  - Ensure `[[MODULE_NAME]]` is replaced in `pyproject.toml`
+  - Update coverage source paths if needed
+  - Add test-specific fixtures in `conftest.py`
+
+- [ ] **Run tests**
+  ```bash
+  pytest
+  ```
+  - Ensure all tests pass
+  - Check coverage meets the 96% threshold
+
+## 🚀 CI/CD Updates
+
+- [ ] **Test CI workflow**
+  - Push your changes to GitHub
+  - Verify the CI workflow runs successfully
+  - Check that coverage reports are generated correctly
+
+- [ ] **Set up Codecov** (optional)
+  - If using Codecov, add your repository token to GitHub secrets
+  - Update `CODECOV_TOKEN` in repository settings
+
+## 📄 License
+
+- [ ] **Review license**
+  - Template uses MIT License
+  - Update LICENSE file if you need a different license
+  - Update `license = "MIT"` in `pyproject.toml` if changed
+
+## 🗑️ Remove Unnecessary Files
+
+- [ ] **Remove template documentation**
+  - Delete `POST_INIT_CHECKLIST.md` after completing all steps
+  - Delete `TEMPLATE_GUIDE.md` (if you no longer need it)
+  - Consider creating your own contributing guide
+
+## ✅ Final Verification
+
+- [ ] **Run all checks**
+  ```bash
+  make lint
+  make pytest
+  ```
+  - Ensure linting passes
+  - Ensure tests pass with adequate coverage
+
+- [ ] **Test your project**
+  - Install your package: `pip install -e .`
+  - Test your public API
+  - Verify documentation is clear and accurate
+
+- [ ] **Commit your changes**
+  ```bash
+  git add .
+  git commit -m "chore: customize project after initialization"
+  ```
+
+## 🎉 You're Done!
+
+Your project is now fully configured and ready for development. Remember to:
+
+- Keep documentation updated as you add features
+- Maintain test coverage above 96%
+- Follow the coding patterns defined in AGENTS.md
+- Use conventional commits for your commit messages
+
+For questions or issues, refer to the project documentation or create an issue in your repository.