Fix expert review issues: license format, PEP 735, nav, deprecation example

Critical:
- license = { text = "MIT" } → license = "MIT" (PEP 639)
- uv add --dev → uv add --group dev (PEP 735 dependency-groups)
- [dependency-groups] in scaffold pyproject.toml replaces legacy dev-deps

Important:
- Removed deprecated target-version from ruff config
- Added Python classifiers to scaffold pyproject.toml
- Fixed mkdocs nav to only reference files scaffold creates
- Fixed deprecation example (charset→encoding instead of confusing sep/delimiter)
- setup-uv@v3 → @v4
- uv sync --all-extras --dev → uv sync --group dev in CI
- Fixed importlib.metadata fallback to catch PackageNotFoundError specifically
- Clarified hatchling wheel exclude is unnecessary with src layout
- Added /pyckage check subcommand for anti-pattern audit
- Added no-args assessment checklist (5 structural checks)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Naareman

README.md

@@ -45,6 +45,7 @@ pyckage activates automatically when you're working on Python package tasks. You
 /pyckage docs                       # Set up mkdocs + docstrings
 /pyckage lifecycle                  # Manage deprecations and versioning
 /pyckage release                    # Walk through the PyPI release ritual
+/pyckage check                      # Audit your project for common mistakes
 /pyckage                            # Assess your project against all 5 principles
 ```
 

SKILL.md

@@ -6,7 +6,7 @@ description: >
   mkdocs-material. Activate when creating/structuring Python packages, designing APIs,
   naming functions, adding user messages/errors, writing tests, setting up docs, managing
   deprecations, or publishing to PyPI.
-argument-hint: "[scaffold|api|test|docs|lifecycle|release] [package-name]"
+argument-hint: "[scaffold|api|test|docs|lifecycle|release|check] [package-name]"
 ---
 
 # pyckage
@@ -108,9 +108,18 @@ When invoked with `/pyckage <subcommand>`, route based on the first argument:
 | `/pyckage docs` | Read [references/04-docs.md](references/04-docs.md) and set up or improve documentation |
 | `/pyckage lifecycle` | Read [references/05-lifecycle.md](references/05-lifecycle.md) and manage deprecations |
 | `/pyckage release` | Read [references/06-release.md](references/06-release.md) and walk through the release ritual |
-| `/pyckage` (no args) | Assess the current project against all five principles and suggest improvements |
+| `/pyckage check` | Read [references/07-common-mistakes.md](references/07-common-mistakes.md) and audit current project for anti-patterns |
+| `/pyckage` (no args) | Assess the current project against all five principles (see checklist below) |
 
-When invoked without a subcommand (auto-triggered or plain `/pyckage`), use the Quick Decision Guide below.
+When invoked without a subcommand (auto-triggered or plain `/pyckage`), run this assessment:
+
+1. **Structure** — Is there a `src/` layout? Does `__init__.py` have `__all__`?
+2. **Communication** — Is there an `errors.py` with a base exception? A `_messages.py` with `rich`?
+3. **Naming** — Do public functions follow `verb_noun()`? Are families consistent?
+4. **Documentation** — Do all public functions have Google-style docstrings?
+5. **Lifecycle** — Is `__version__` from `importlib.metadata`? Is there a CHANGELOG?
+
+Then use the Quick Decision Guide below for any specific improvements.
 
 ---
 

references/01-scaffold.md

@@ -18,7 +18,7 @@ cd my-package
 
 # 3. Add core dependencies
 uv add rich          # user messages
-uv add --dev pytest pytest-cov ruff mypy mkdocs-material mkdocstrings[python]
+uv add --group dev pytest pytest-cov ruff mypy mkdocs-material mkdocstrings[python]
 
 # 4. Initialize git
 git init
@@ -40,9 +40,16 @@ name = "my-package"
 version = "0.1.0"
 description = "One clear sentence describing what this does."
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
 dependencies = [
     "rich>=13.0",
 ]
@@ -52,6 +59,16 @@ Homepage = "https://github.com/you/my-package"
 Documentation = "https://you.github.io/my-package"
 Repository = "https://github.com/you/my-package"
 
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+    "mypy>=1.0",
+    "mkdocs-material>=9.0",
+    "mkdocstrings[python]>=0.25",
+]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -61,7 +78,6 @@ packages = ["src/my_package"]
 
 [tool.ruff]
 line-length = 88
-target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP"]

references/04-docs.md

@@ -83,9 +83,7 @@ plugins:
 
 nav:
   - Home: index.md
-  - Getting Started: getting-started.md
   - API Reference: api.md
-  - Changelog: changelog.md
 ```
 
 ### `docs/api.md` — auto-generated from docstrings

references/05-lifecycle.md

@@ -106,12 +106,12 @@ def read_data(path):
 When an argument is renamed or removed:
 
 ```python
-def read_csv(path, encoding="utf-8", *, sep=None, delimiter=None):
+def read_csv(path, *, charset=None, encoding="utf-8"):
     """..."""
-    if sep is not None:
-        deprecated("sep", "delimiter", version="0.5.0")
-        delimiter = sep
-    # use delimiter going forward
+    if charset is not None:
+        deprecated("charset", "encoding", version="0.5.0")
+        encoding = charset
+    # use encoding going forward
 ```
 
 ---

references/06-release.md

@@ -90,13 +90,13 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v4
 
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --all-extras --dev
+        run: uv sync --group dev
 
       - name: Lint
         run: uv run ruff check src/
@@ -129,7 +129,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v4
 
       - name: Build
         run: uv build
@@ -162,7 +162,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v4
 
       - name: Install dependencies
         run: uv sync --dev

references/07-common-mistakes.md

@@ -41,7 +41,8 @@ locally but the installed package may be broken (missing files, wrong imports).
 ### Including tests/ in the wheel
 **Mistake:** Build includes a top-level `tests/` in the wheel.
 **Why:** Writes to `site-packages/tests/`, colliding with other packages.
-**Fix:** With hatchling, use `[tool.hatch.build.targets.wheel] exclude = ["tests"]`.
+**Fix:** With src layout + `packages = ["src/my_package"]`, tests are excluded automatically.
+For flat layouts, explicitly exclude: `[tool.hatch.build.targets.wheel] exclude = ["tests"]`.
 
 ### Putting `__init__.py` in tests/
 **Why:** Confuses package discovery. Tests should never be importable.
@@ -143,9 +144,9 @@ __version__ = version("my-package")
 **Fix:**
 ```python
 try:
-    from importlib.metadata import version
+    from importlib.metadata import version, PackageNotFoundError
     __version__ = version("my-package")
-except Exception:
+except PackageNotFoundError:
     __version__ = "0.0.0"
 ```