From 35213e83874563897d77504a8ff60583ddbcf8e4 Mon Sep 17 00:00:00 2001 From: Gale W Date: Thu, 14 May 2026 17:18:40 -0400 Subject: [PATCH 1/6] plugin: repair python-skills validator and plan expansion --- ROADMAP.md | 34 ++ TODO.md | 12 +- docs/maintainers/python-skills-plugin-plan.md | 302 ++++++++++++++++++ .../scripts/validate_repo_metadata.py | 50 +-- .../python-skills/tests/test_plugin_smoke.py | 7 +- 5 files changed, 366 insertions(+), 39 deletions(-) create mode 100644 docs/maintainers/python-skills-plugin-plan.md diff --git a/ROADMAP.md b/ROADMAP.md index fb2cebb5..e4dc5cd1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -7,6 +7,7 @@ - [Milestone Progress](#milestone-progress) - [Milestone 5: SwiftASB skills plugin](#milestone-5-swiftasb-skills-plugin) - [Milestone 6: Dotnet skills plugin](#milestone-6-dotnet-skills-plugin) +- [Milestone 7: Python skills plugin expansion](#milestone-7-python-skills-plugin-expansion) - [Backlog Candidates](#backlog-candidates) - [History](#history) @@ -25,6 +26,7 @@ - Milestone 5: SwiftASB skills plugin - In Progress - Milestone 6: Dotnet skills plugin - In Progress +- Milestone 7: Python skills plugin expansion - In Progress ## Milestone 5: SwiftASB skills plugin @@ -88,6 +90,38 @@ In Progress - [x] The testing guidance uses `dotnet test` as the stable command surface while respecting repo-local test framework choices. - [x] Root Socket docs, marketplace wiring, and validation agree on the plugin's install surface. +## Milestone 7: Python skills plugin expansion + +### Status + +In Progress + +### Scope + +- [x] Repair the `python-skills` child validator so it matches the current monorepo-owned child docs model without reintroducing a child README. +- [x] Record the detailed expansion plan in [`docs/maintainers/python-skills-plugin-plan.md`](./docs/maintainers/python-skills-plugin-plan.md). +- [ ] Expand `python-skills` from scaffold-heavy coverage into ongoing project choice, implementation, diagnostics, packaging, and tooling/style workflows. +- [ ] Keep the existing `uv`, FastAPI, FastMCP, and pytest skill surfaces intact unless a later cleanup deliberately renames or replaces one without leaving duplicate long-term surfaces. + +### Tickets + +- [x] Update `plugins/python-skills/scripts/validate_repo_metadata.py` and child tests so validation targets `AGENTS.md`, plugin metadata, and skill metadata instead of a removed child `README.md`. +- [ ] Add `python-skills:choose-python-project-shape`. +- [ ] Add `python-skills:build-python-project`. +- [ ] Add `python-skills:diagnose-python-project`. +- [ ] Add `python-skills:python-package-workflow`. +- [ ] Add `python-skills:python-tooling-style-workflow`. +- [ ] Update Python plugin metadata after the first new skill slice lands. +- [ ] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. +- [ ] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. + +### Exit Criteria + +- [ ] The child validator passes without requiring a child `README.md`. +- [ ] The Python skill inventory covers project choice, implementation, diagnostics, packaging, and tooling/style alignment in addition to existing scaffold, integration, and pytest workflows. +- [ ] The Python plugin guidance consistently uses `uv` for command examples and official documentation as the source of truth for Python packaging, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. +- [ ] Root Socket docs, marketplace wiring, child validation, and root validation agree on the exported Python skill surface. + ## Backlog Candidates - [x] Overhaul `agent-plugin-skills` so its docs, tests, generated bootstrap content, and sync audit logic target Codex/OpenAI plus the open `.agents/skills` discovery mirror only. Remove stale expectations for retired child maintainer docs such as reality-audit and install-surface docs, and keep the wording away from unsupported non-Codex or generic multi-agent surfaces. diff --git a/TODO.md b/TODO.md index e7aae9c6..6f4dbce4 100644 --- a/TODO.md +++ b/TODO.md @@ -35,9 +35,15 @@ This file is the Socket-level backlog for child plugins that no longer keep thei ### python-skills - [x] Tighten child-specific `AGENTS.md` and validator expectations after the README collapse. -- [ ] Keep `skills/`, `.codex-plugin/plugin.json`, and Socket-root contribution workflow boundaries clearly separated. -- [ ] Confirm `uv run scripts/validate_repo_metadata.py` and `uv run pytest` still pass after docs or metadata changes. -- [ ] Add lightweight validation for future Codex metadata changes. +- [x] Fix the child validator so it no longer expects a removed child `README.md`. +- [x] Record the expansion plan in [`docs/maintainers/python-skills-plugin-plan.md`](./docs/maintainers/python-skills-plugin-plan.md). +- [ ] Add `choose-python-project-shape`. +- [ ] Add `build-python-project`. +- [ ] Add `diagnose-python-project`. +- [ ] Add `python-package-workflow`. +- [ ] Add `python-tooling-style-workflow`. +- [ ] Update `plugins/python-skills/.codex-plugin/plugin.json` after the new skills exist. +- [ ] Confirm `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .` pass after skill or metadata changes. ### swiftasb-skills diff --git a/docs/maintainers/python-skills-plugin-plan.md b/docs/maintainers/python-skills-plugin-plan.md new file mode 100644 index 00000000..9ebe922a --- /dev/null +++ b/docs/maintainers/python-skills-plugin-plan.md @@ -0,0 +1,302 @@ +# Python Skills Plugin Expansion Plan + +This plan records the next durable shape for the Socket-hosted `python-skills` plugin. + +The plugin already has a useful scaffold and integration surface. The next job is to make it help agents keep working after the first project exists: choose the right Python project shape, write idiomatic Python, diagnose failures, validate package surfaces, align tooling, and keep CI and upgrades grounded in the same `uv` command vocabulary. + +## Intent + +The `python-skills` plugin should help agents do seven things: + +- choose a Python project shape before scaffolding or implementation starts +- bootstrap reproducible `uv` projects, services, workspaces, tests, FastAPI apps, and FastMCP servers +- write idiomatic Python that respects the repository's package layout, type-checking strictness, configuration model, and test boundaries +- run and explain Python test, lint, format, type-check, package, and diagnostics workflows +- maintain Python packaging metadata without accidentally publishing or relying on machine-local paths +- align local commands, CI checks, and upgrade work around `uv` +- keep FastAPI and FastMCP guidance grounded in official documentation and curated MCP ergonomics + +This remains a companion guidance plugin, not a runtime plugin. Do not add an MCP server, daemon, custom package registry, private template feed, or machine-local interpreter state unless a later plan explicitly approves that scope. + +## Packaging Direction + +Keep the guidance as a monorepo-owned child plugin under: + +```text +plugins/python-skills/ +``` + +The child plugin owns: + +- `.codex-plugin/plugin.json` +- `skills/` +- per-skill `agents/openai.yaml` +- child `AGENTS.md` +- child-local validation scripts and tests for plugin metadata, skill metadata, scaffold smoke tests, and exported workflow contracts + +Do not reintroduce a child `README.md` or per-skill `README.md` files by default. Socket's root README remains the user-facing catalog surface, child `AGENTS.md` remains the child operating contract, and this maintainer plan records expansion decisions. + +## Naming Convention + +Use names that describe what the skill asks the agent to do. + +Prefer action-first names when the skill is primarily a directed action: + +- `choose-python-project-shape` +- `build-python-project` +- `diagnose-python-project` + +Prefer subject-workflow names when the skill is primarily an ongoing maintenance or operating surface: + +- `python-package-workflow` +- `python-tooling-style-workflow` +- `python-ci-workflow` +- `python-upgrade-workflow` +- `python-testing-workflow` + +Keep existing names unless a cleanup slice explicitly renames the skill and removes the old duplicate surface in the same pass. Do not leave compatibility shims or duplicate overlapping skill paths behind unless Gale explicitly approves that compromise. + +## Documentation Sources + +Use official documentation first for Python behavior: + +- [uv documentation](https://docs.astral.sh/uv/) +- [Python packaging user guide](https://packaging.python.org/) +- [Writing `pyproject.toml`](https://packaging.python.org/guides/writing-pyproject-toml/) +- [pytest documentation](https://docs.pytest.org/en/stable/) +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [mypy documentation](https://mypy.readthedocs.io/en/stable/) +- [FastAPI documentation](https://fastapi.tiangolo.com/) +- [FastMCP documentation](https://gofastmcp.com/getting-started/welcome) +- [GitHub Actions Python documentation](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python) + +When a skill relies on documentation, translate the relevant rule into practical workflow guidance. Explain what the doc changes about command choice, package layout, validation scope, configuration, CI, or upgrade risk. + +## Current Skill Inventory + +### `python-skills:bootstrap-uv-python-workspace` + +Keep this as the shared `uv` scaffolding basis. + +It should continue to own deterministic project and workspace generation, profile-driven scaffolding, initial `pytest`/`ruff`/`mypy` setup, safe `.env` defaults, and generated next-step commands. + +### `python-skills:bootstrap-python-service` + +Keep this as the FastAPI-first scaffold path. + +It should stay focused on creating new services. Ongoing endpoint, dependency, configuration, and deployment changes belong in a future service workflow rather than making this bootstrap skill too broad. + +### `python-skills:bootstrap-python-mcp-service` + +Keep this as the FastMCP-first scaffold path. + +It should stay focused on creating new MCP server projects and mapping existing APIs into MCP review reports. Ongoing MCP surface design can grow later if repeated FastMCP maintenance work needs its own skill. + +### `python-skills:integrate-fastapi-fastmcp` + +Keep this as the existing integration bridge. + +It should continue to cover mounted FastMCP apps, FastAPI-derived MCP surfaces, combined app shapes, lifespan boundaries, and promotion from generated MCP surfaces to curated MCP tools and resources. + +### `python-skills:uv-pytest-unit-testing` + +Keep this for now as the tested pytest setup and execution surface. + +Consider renaming or replacing it with `python-testing-workflow` only in a cleanup slice that broadens the skill to cover test selection, failure explanation, coverage, async tests, integration tests, and CI parity. Do not keep both names as long-term duplicates. + +## Proposed Skill Inventory + +### `python-skills:choose-python-project-shape` + +Help an agent decide how Python should fit into a user's project before implementation starts. + +This skill should classify the requested work: + +- single-package library +- command-line app +- FastAPI service +- FastMCP server +- combined FastAPI and FastMCP surface +- `uv` workspace +- test-only or tooling-only change +- packaging, CI, or upgrade pass +- mixed-language repository where Python is only one project member + +The output should recommend project shape, package layout, validation commands, dependency group strategy, generated files, and documentation updates. It should hand off to existing bootstrap skills when scaffolding is the next step. + +### `python-skills:build-python-project` + +Guide agents through implementation in an existing Python project. + +This skill should cover: + +- reading `pyproject.toml`, package layout, tests, and existing style before editing +- choosing module boundaries that keep imports straightforward +- preserving typed configuration and environment boundaries +- using small composable functions and explicit inputs/outputs where practical +- keeping framework adapters thin around reusable project logic +- adding focused tests around changed behavior +- running the narrowest useful `uv run` validation command first + +This is the general implementation skill, not a replacement for specialized FastAPI, FastMCP, package, test, or CI workflows. + +### `python-skills:diagnose-python-project` + +Help agents find the first meaningful cause of Python failures. + +This skill should cover: + +- missing or mismatched Python versions +- `uv` sync, lock, and dependency-group issues +- import path and package layout problems +- test discovery and fixture failures +- Ruff lint or format failures +- mypy configuration, missing stubs, and type-check failures +- FastAPI app import or lifespan failures +- FastMCP server startup and tool-registration failures +- packaging metadata and build failures + +Diagnostics should report what command failed, which phase failed, the likely cause, and the smallest useful next check. + +### `python-skills:python-package-workflow` + +Validate Python package surfaces before release or publication. + +This skill should cover: + +- package metadata in `pyproject.toml` +- build-system selection and package discovery +- dependency versus optional dependency versus dependency-group boundaries +- README, license, classifiers, project URLs, and package description expectations +- local build validation +- local package smoke checks +- semantic versioning and release notes +- PyPI or private index publication as an explicit release step only + +It should not publish packages unless the user explicitly asks for that release step or repo-local release automation owns it. + +### `python-skills:python-tooling-style-workflow` + +Align Python formatting, linting, type checking, and local tooling. + +This skill should cover: + +- Ruff formatter and linter setup +- mypy configuration and staged strictness +- `pytest` configuration when it intersects with tooling +- `pyproject.toml` versus dedicated config file choices +- dependency groups for maintainer tools +- pre-commit or editor integration only when the repo already uses it or the user asks +- keeping formatting-only sweeps separate from behavior changes when practical + +The workflow should preserve repo-local conventions and avoid forcing strictness upgrades into unrelated feature work. + +### `python-skills:python-ci-workflow` + +Guide agents through Python CI setup and maintenance. + +This skill should cover: + +- GitHub Actions setup for Python and `uv` +- dependency caching choices +- `uv sync --dev` or equivalent repo-local install commands +- `uv run pytest` +- `uv run ruff check .` +- `uv run ruff format --check .` when formatting is enforced +- `uv run mypy .` +- package build checks when package surfaces exist +- matrix decisions for Python versions and operating systems + +CI should prove the same behavior maintainers care about locally and avoid publishing as a side effect. + +### `python-skills:python-upgrade-workflow` + +Guide agents through Python, dependency, framework, and tooling upgrades. + +This skill should cover: + +- current Python version requirements +- `uv.lock` +- dependency groups and optional dependencies +- FastAPI, FastMCP, Pydantic, Ruff, mypy, and pytest upgrade notes +- staged validation +- contributor setup or package-consumer migration notes when requirements change + +Use this when changing Python version support, package versions, lockfiles, or framework major versions. + +## First Implementation Slice + +The first slice should repair the current child contract and add the core missing operating skills: + +- [x] Fix `plugins/python-skills/scripts/validate_repo_metadata.py` so it validates the child `AGENTS.md`, plugin manifest, and skill metadata without expecting a removed child `README.md`. +- [x] Update child tests so they assert the current no-child-README contract. +- [x] Record this expansion plan. +- [ ] Add `python-skills:choose-python-project-shape`. +- [ ] Add `python-skills:build-python-project`. +- [ ] Add `python-skills:diagnose-python-project`. +- [ ] Add `python-skills:python-package-workflow`. +- [ ] Add `python-skills:python-tooling-style-workflow`. +- [ ] Update `plugins/python-skills/.codex-plugin/plugin.json` default prompts and long description after the new skills exist. +- [ ] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. +- [ ] Run root Socket metadata validation with `uv run scripts/validate_socket_metadata.py`. + +## Second Implementation Slice + +The second slice should cover repeated project operations that become more valuable after the core skill set lands: + +- [ ] Add `python-skills:python-ci-workflow`. +- [ ] Add `python-skills:python-upgrade-workflow`. +- [ ] Decide whether to broaden `uv-pytest-unit-testing` into `python-testing-workflow`. +- [ ] Decide whether ongoing FastAPI service maintenance needs a dedicated `fastapi-service-workflow`. +- [ ] Decide whether ongoing FastMCP server maintenance needs a dedicated `fastmcp-service-workflow`. +- [ ] Add install testing with a temporary `CODEX_HOME` if the exported skill surface or plugin metadata changes enough to need plugin-install verification. + +## Deferred Scope + +After the first two slices prove useful, consider deeper specialized workflows: + +- data science and notebook workflows +- Django workflows +- Typer or Click CLI workflows +- async service performance diagnostics +- package publishing automation +- Python MCP server runtime diagnostics beyond FastMCP guidance +- generated project-template maintenance beyond the current shell scaffold scripts +- bundled MCP servers or app connectors + +## Open Decisions Before Implementation + +### Testing Skill Name + +Decision for now: keep `uv-pytest-unit-testing`. + +A future cleanup can rename or replace it with `python-testing-workflow` when the scope grows beyond unit-test setup and `uv`-targeted pytest execution. If that cleanup happens, remove the old duplicate skill path in the same pass unless Gale explicitly approves a compatibility period. + +### Service Workflow Timing + +Decision for the first slice: defer ongoing FastAPI and FastMCP service workflows. + +The existing bootstrap and integration skills already cover new service creation and combined FastAPI/FastMCP architecture. Add service-maintenance workflows only after the general `build-python-project` and `diagnose-python-project` skills prove where specialized service guidance should branch. + +### Script Depth + +Decision for the first slice: keep the new operating skills as guidance-first. + +The existing bootstrap and pytest skills already own deterministic shell entrypoints. Add scripts to new skills only when repeated command generation or validation behavior becomes mechanical enough to test directly. + +### Versioning And Marketplace Timing + +Decision for this expansion: treat the full first implementation slice as a likely Socket minor release candidate. + +The validator repair alone is a maintenance fix. Adding the new skill inventory is user-facing plugin capability and should likely publish as a minor release when the branch is ready. + +## Definition Of Done + +The expansion is ready when: + +- [ ] The child validator passes without requiring a child `README.md`. +- [ ] The plugin has a documented skill naming convention and expansion plan. +- [ ] The first new skill set covers project choice, implementation, diagnostics, packaging, and tooling/style alignment. +- [ ] The guidance consistently uses `uv` for Python command examples. +- [ ] The guidance uses official documentation as the source of truth for Python packaging, `uv`, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. +- [ ] Root Socket docs, plugin metadata, child validation, and root validation agree on the exported Python skill surface. diff --git a/plugins/python-skills/scripts/validate_repo_metadata.py b/plugins/python-skills/scripts/validate_repo_metadata.py index 14a37ca6..00e611a8 100755 --- a/plugins/python-skills/scripts/validate_repo_metadata.py +++ b/plugins/python-skills/scripts/validate_repo_metadata.py @@ -21,21 +21,6 @@ NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$") HEX_COLOR_RE = re.compile(r"^#[0-9A-Fa-f]{6}$") -README_REQUIRED_HEADINGS = [ - "# python-skills", - "## Table of Contents", - "## Overview", - "## Setup", - "## Usage", - "## Development", - "## Verification", - "## Release Notes", - "## Active Skills", - "## Packaging", - "## Repository Layout", - "## License", -] - PATH_REFERENCE_RE = re.compile( r"(?:\[[^\]]+\]\()?((?:scripts|references|assets|agents)/[A-Za-z0-9._/\-]+)(?:\))?" ) @@ -211,13 +196,23 @@ def find_skill_dirs(repo_root: Path) -> list[Path]: ) -def validate_readme(repo_root: Path) -> list[Finding]: +def validate_child_guidance(repo_root: Path) -> list[Finding]: findings: list[Finding] = [] - readme = repo_root / "README.md" - text = readme.read_text() - for heading in README_REQUIRED_HEADINGS: - if heading not in text: - findings.append(Finding("README.md", f"missing heading: {heading}")) + agents = repo_root / "AGENTS.md" + if not agents.is_file(): + return [Finding("AGENTS.md", "missing child guidance file")] + + text = agents.read_text() + required_snippets = [ + "`python-skills` is a monorepo-owned Socket child", + "Root [`skills/`](./skills/) is the authored workflow surface.", + "The repo root is the Codex plugin root through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json).", + "Do not reintroduce maintained per-skill `README.md` files", + "Keep user-facing and maintainer-facing Python command examples expressed with `uv`.", + ] + for snippet in required_snippets: + if snippet not in text: + findings.append(Finding("AGENTS.md", f"missing guidance snippet: {snippet}")) return findings @@ -343,22 +338,12 @@ def validate_plugin_manifest( return findings -def validate_doc_inventory(repo_root: Path, skill_dirs: list[Path]) -> list[Finding]: - findings: list[Finding] = [] - readme_text = (repo_root / "README.md").read_text() - for skill_dir in skill_dirs: - skill_name = skill_dir.name - if f"`{skill_name}`" not in readme_text: - findings.append(Finding("README.md", f"skill missing from root docs: {skill_name}")) - return findings - - def run(repo_root: Path) -> list[Finding]: findings: list[Finding] = [] skill_dirs = find_skill_dirs(repo_root) if not skill_dirs: findings.append(Finding("skills", "no bundled skill directories found under skills/")) - findings.extend(validate_readme(repo_root)) + findings.extend(validate_child_guidance(repo_root)) findings.extend( validate_plugin_manifest( repo_root, @@ -367,7 +352,6 @@ def run(repo_root: Path) -> list[Finding]: require_skills_interface=True, ) ) - findings.extend(validate_doc_inventory(repo_root, skill_dirs)) for skill_dir in skill_dirs: findings.extend(validate_skill_dir(repo_root, skill_dir)) return findings diff --git a/plugins/python-skills/tests/test_plugin_smoke.py b/plugins/python-skills/tests/test_plugin_smoke.py index b60c6f78..33e597ac 100644 --- a/plugins/python-skills/tests/test_plugin_smoke.py +++ b/plugins/python-skills/tests/test_plugin_smoke.py @@ -29,15 +29,16 @@ def run_command(*args: str, cwd: Path | None = None) -> subprocess.CompletedProc def test_plugin_manifest_and_marketplace_contract() -> None: manifest = json.loads((REPO_ROOT / ".codex-plugin" / "plugin.json").read_text()) - readme_text = (REPO_ROOT / "README.md").read_text() + agents_text = (REPO_ROOT / "AGENTS.md").read_text() assert manifest["name"] == "python-skills" assert manifest["skills"] == "./skills/" assert manifest["interface"]["displayName"] == "Python Skills" assert manifest["interface"]["category"] == "Productivity" - assert ".codex-plugin/plugin.json" in readme_text - assert "root [`skills/`](./skills/) is the canonical authored workflow surface" in readme_text + assert ".codex-plugin/plugin.json" in agents_text + assert "Root [`skills/`](./skills/) is the authored workflow surface" in agents_text + assert not (REPO_ROOT / "README.md").exists() def test_fastapi_scaffold_smoke(tmp_path: Path) -> None: From 5d08ea70bf3b999e1ed8c5594c9794e9095a8517 Mon Sep 17 00:00:00 2001 From: Gale W Date: Thu, 14 May 2026 19:01:18 -0400 Subject: [PATCH 2/6] plugin: add python project workflow skills --- .agents/plugins/marketplace.json | 2 +- README.md | 2 +- ROADMAP.md | 18 +- TODO.md | 12 +- docs/architecture/ARCHITECTURE.md | 38 +- docs/architecture/architecture.json | 512 +++++++++++++++++- docs/maintainers/python-skills-plugin-plan.md | 16 +- .../python-skills/.codex-plugin/plugin.json | 18 +- .../skills/build-python-project/SKILL.md | 124 +++++ .../build-python-project/agents/openai.yaml | 8 + .../choose-python-project-shape/SKILL.md | 111 ++++ .../agents/openai.yaml | 8 + .../skills/diagnose-python-project/SKILL.md | 123 +++++ .../agents/openai.yaml | 8 + .../skills/python-package-workflow/SKILL.md | 119 ++++ .../agents/openai.yaml | 8 + .../python-tooling-style-workflow/SKILL.md | 133 +++++ .../agents/openai.yaml | 8 + .../python-skills/tests/test_plugin_smoke.py | 2 +- 19 files changed, 1235 insertions(+), 35 deletions(-) create mode 100644 plugins/python-skills/skills/build-python-project/SKILL.md create mode 100644 plugins/python-skills/skills/build-python-project/agents/openai.yaml create mode 100644 plugins/python-skills/skills/choose-python-project-shape/SKILL.md create mode 100644 plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml create mode 100644 plugins/python-skills/skills/diagnose-python-project/SKILL.md create mode 100644 plugins/python-skills/skills/diagnose-python-project/agents/openai.yaml create mode 100644 plugins/python-skills/skills/python-package-workflow/SKILL.md create mode 100644 plugins/python-skills/skills/python-package-workflow/agents/openai.yaml create mode 100644 plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md create mode 100644 plugins/python-skills/skills/python-tooling-style-workflow/agents/openai.yaml diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index de9302d6..01c4ae34 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -93,7 +93,7 @@ "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, - "category": "Productivity" + "category": "Developer Tools" }, { "name": "rust-skills", diff --git a/README.md b/README.md index d542f1f3..25e43155 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ Current Socket catalog shape: - `cardhop-app`: mixed skill plus bundled MCP server for Cardhop.app contact workflows - `dotnet-skills`: .NET, F#, and C# project-shape, bootstrap, implementation, test, package, diagnostics, ASP.NET Core, interop, CI, upgrade, and tooling guidance - `productivity-skills`: general-purpose maintainer and documentation workflow baseline -- `python-skills`: Python, `uv`, FastAPI, FastMCP, and pytest workflow plugin +- `python-skills`: Python, `uv`, project implementation, diagnostics, packaging, tooling, FastAPI, FastMCP, and pytest workflow plugin - `speak-swiftly`: Git-backed Speak Swiftly plugin from the standalone SpeakSwiftlyServer repository - `swiftasb-skills`: SwiftASB companion guidance - `things-app`: mixed skill plus bundled MCP server for Things.app workflows diff --git a/ROADMAP.md b/ROADMAP.md index e4dc5cd1..26e25304 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -100,25 +100,25 @@ In Progress - [x] Repair the `python-skills` child validator so it matches the current monorepo-owned child docs model without reintroducing a child README. - [x] Record the detailed expansion plan in [`docs/maintainers/python-skills-plugin-plan.md`](./docs/maintainers/python-skills-plugin-plan.md). -- [ ] Expand `python-skills` from scaffold-heavy coverage into ongoing project choice, implementation, diagnostics, packaging, and tooling/style workflows. +- [x] Expand `python-skills` from scaffold-heavy coverage into ongoing project choice, implementation, diagnostics, packaging, and tooling/style workflows. - [ ] Keep the existing `uv`, FastAPI, FastMCP, and pytest skill surfaces intact unless a later cleanup deliberately renames or replaces one without leaving duplicate long-term surfaces. ### Tickets - [x] Update `plugins/python-skills/scripts/validate_repo_metadata.py` and child tests so validation targets `AGENTS.md`, plugin metadata, and skill metadata instead of a removed child `README.md`. -- [ ] Add `python-skills:choose-python-project-shape`. -- [ ] Add `python-skills:build-python-project`. -- [ ] Add `python-skills:diagnose-python-project`. -- [ ] Add `python-skills:python-package-workflow`. -- [ ] Add `python-skills:python-tooling-style-workflow`. -- [ ] Update Python plugin metadata after the first new skill slice lands. +- [x] Add `python-skills:choose-python-project-shape`. +- [x] Add `python-skills:build-python-project`. +- [x] Add `python-skills:diagnose-python-project`. +- [x] Add `python-skills:python-package-workflow`. +- [x] Add `python-skills:python-tooling-style-workflow`. +- [x] Update Python plugin metadata after the first new skill slice lands. - [ ] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. - [ ] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. ### Exit Criteria -- [ ] The child validator passes without requiring a child `README.md`. -- [ ] The Python skill inventory covers project choice, implementation, diagnostics, packaging, and tooling/style alignment in addition to existing scaffold, integration, and pytest workflows. +- [x] The child validator passes without requiring a child `README.md`. +- [x] The Python skill inventory covers project choice, implementation, diagnostics, packaging, and tooling/style alignment in addition to existing scaffold, integration, and pytest workflows. - [ ] The Python plugin guidance consistently uses `uv` for command examples and official documentation as the source of truth for Python packaging, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. - [ ] Root Socket docs, marketplace wiring, child validation, and root validation agree on the exported Python skill surface. diff --git a/TODO.md b/TODO.md index 6f4dbce4..537524d0 100644 --- a/TODO.md +++ b/TODO.md @@ -37,12 +37,12 @@ This file is the Socket-level backlog for child plugins that no longer keep thei - [x] Tighten child-specific `AGENTS.md` and validator expectations after the README collapse. - [x] Fix the child validator so it no longer expects a removed child `README.md`. - [x] Record the expansion plan in [`docs/maintainers/python-skills-plugin-plan.md`](./docs/maintainers/python-skills-plugin-plan.md). -- [ ] Add `choose-python-project-shape`. -- [ ] Add `build-python-project`. -- [ ] Add `diagnose-python-project`. -- [ ] Add `python-package-workflow`. -- [ ] Add `python-tooling-style-workflow`. -- [ ] Update `plugins/python-skills/.codex-plugin/plugin.json` after the new skills exist. +- [x] Add `choose-python-project-shape`. +- [x] Add `build-python-project`. +- [x] Add `diagnose-python-project`. +- [x] Add `python-package-workflow`. +- [x] Add `python-tooling-style-workflow`. +- [x] Update `plugins/python-skills/.codex-plugin/plugin.json` after the new skills exist. - [ ] Confirm `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .` pass after skill or metadata changes. ### swiftasb-skills diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index c1da04fe..0ce8e073 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -13,7 +13,7 @@ See [SLICES.md](./SLICES.md) for provable end-to-end code paths. - `agent-plugin-skills` (codex-plugin) uses targets: skills:plugins/agent-plugin-skills/skills. - `apple-dev-skills` (codex-plugin) uses targets: skills:plugins/apple-dev-skills/skills, mcp:plugins/apple-dev-skills/.mcp.json. - `cardhop-app` (codex-plugin) uses targets: skills:plugins/cardhop-app/skills, mcp:plugins/cardhop-app/.mcp.json. -- `dotnet-skills` (codex-plugin) uses targets: no targets recorded. +- `dotnet-skills` (codex-plugin) uses targets: skills:plugins/dotnet-skills/skills. - `productivity-skills` (codex-plugin) uses targets: skills:plugins/productivity-skills/skills. - `python-skills` (codex-plugin) uses targets: skills:plugins/python-skills/skills. - `rust-skills` (codex-plugin) uses targets: no targets recorded. @@ -38,6 +38,7 @@ See [SLICES.md](./SLICES.md) for provable end-to-end code paths. - `skill:apple-dev-skills/bootstrap-xcode-app-project` (codex-skill) at `plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md` depends on: no declared dependencies. - `skill:apple-dev-skills/explore-apple-swift-docs` (codex-skill) at `plugins/apple-dev-skills/skills/explore-apple-swift-docs/SKILL.md` depends on: no declared dependencies. - `skill:apple-dev-skills/format-swift-sources` (codex-skill) at `plugins/apple-dev-skills/skills/format-swift-sources/SKILL.md` depends on: no declared dependencies. +- `skill:apple-dev-skills/safari-extension-control-workflow` (codex-skill) at `plugins/apple-dev-skills/skills/safari-extension-control-workflow/SKILL.md` depends on: no declared dependencies. - `skill:apple-dev-skills/structure-swift-sources` (codex-skill) at `plugins/apple-dev-skills/skills/structure-swift-sources/SKILL.md` depends on: no declared dependencies. - `skill:apple-dev-skills/swift-package-build-run-workflow` (codex-skill) at `plugins/apple-dev-skills/skills/swift-package-build-run-workflow/SKILL.md` depends on: no declared dependencies. - `skill:apple-dev-skills/swift-package-testing-workflow` (codex-skill) at `plugins/apple-dev-skills/skills/swift-package-testing-workflow/SKILL.md` depends on: no declared dependencies. @@ -51,6 +52,18 @@ See [SLICES.md](./SLICES.md) for provable end-to-end code paths. - `mcp:plugins/apple-dev-skills/.mcp.json` (mcp-config) at `plugins/apple-dev-skills/.mcp.json` depends on: no declared dependencies. - `skill:cardhop-app/cardhop-contact-workflow` (codex-skill) at `plugins/cardhop-app/skills/cardhop-contact-workflow/SKILL.md` depends on: no declared dependencies. - `mcp:plugins/cardhop-app/.mcp.json` (mcp-config) at `plugins/cardhop-app/.mcp.json` depends on: no declared dependencies. +- `skill:dotnet-skills/aspnet-core-service-workflow` (codex-skill) at `plugins/dotnet-skills/skills/aspnet-core-service-workflow/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/bootstrap-solution` (codex-skill) at `plugins/dotnet-skills/skills/bootstrap-solution/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/build-csharp-project` (codex-skill) at `plugins/dotnet-skills/skills/build-csharp-project/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/build-fsharp-project` (codex-skill) at `plugins/dotnet-skills/skills/build-fsharp-project/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/choose-project-shape` (codex-skill) at `plugins/dotnet-skills/skills/choose-project-shape/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/ci-workflow` (codex-skill) at `plugins/dotnet-skills/skills/ci-workflow/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/diagnose-project` (codex-skill) at `plugins/dotnet-skills/skills/diagnose-project/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/fsharp-csharp-interop` (codex-skill) at `plugins/dotnet-skills/skills/fsharp-csharp-interop/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/package-workflow` (codex-skill) at `plugins/dotnet-skills/skills/package-workflow/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/testing-workflow` (codex-skill) at `plugins/dotnet-skills/skills/testing-workflow/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/tooling-style-workflow` (codex-skill) at `plugins/dotnet-skills/skills/tooling-style-workflow/SKILL.md` depends on: no declared dependencies. +- `skill:dotnet-skills/upgrade-workflow` (codex-skill) at `plugins/dotnet-skills/skills/upgrade-workflow/SKILL.md` depends on: no declared dependencies. - `skill:productivity-skills/explain-code-slice` (codex-skill) at `plugins/productivity-skills/skills/explain-code-slice/SKILL.md` depends on: no declared dependencies. - `skill:productivity-skills/maintain-project-accessibility` (codex-skill) at `plugins/productivity-skills/skills/maintain-project-accessibility/SKILL.md` depends on: no declared dependencies. - `skill:productivity-skills/maintain-project-agents` (codex-skill) at `plugins/productivity-skills/skills/maintain-project-agents/SKILL.md` depends on: no declared dependencies. @@ -63,7 +76,12 @@ See [SLICES.md](./SLICES.md) for provable end-to-end code paths. - `skill:python-skills/bootstrap-python-mcp-service` (codex-skill) at `plugins/python-skills/skills/bootstrap-python-mcp-service/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/bootstrap-python-service` (codex-skill) at `plugins/python-skills/skills/bootstrap-python-service/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/bootstrap-uv-python-workspace` (codex-skill) at `plugins/python-skills/skills/bootstrap-uv-python-workspace/SKILL.md` depends on: no declared dependencies. +- `skill:python-skills/build-python-project` (codex-skill) at `plugins/python-skills/skills/build-python-project/SKILL.md` depends on: no declared dependencies. +- `skill:python-skills/choose-python-project-shape` (codex-skill) at `plugins/python-skills/skills/choose-python-project-shape/SKILL.md` depends on: no declared dependencies. +- `skill:python-skills/diagnose-python-project` (codex-skill) at `plugins/python-skills/skills/diagnose-python-project/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/integrate-fastapi-fastmcp` (codex-skill) at `plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md` depends on: no declared dependencies. +- `skill:python-skills/python-package-workflow` (codex-skill) at `plugins/python-skills/skills/python-package-workflow/SKILL.md` depends on: no declared dependencies. +- `skill:python-skills/python-tooling-style-workflow` (codex-skill) at `plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/uv-pytest-unit-testing` (codex-skill) at `plugins/python-skills/skills/uv-pytest-unit-testing/SKILL.md` depends on: no declared dependencies. - `skill:swiftasb-skills/build-appkit-app` (codex-skill) at `plugins/swiftasb-skills/skills/build-appkit-app/SKILL.md` depends on: no declared dependencies. - `skill:swiftasb-skills/build-swift-package` (codex-skill) at `plugins/swiftasb-skills/skills/build-swift-package/SKILL.md` depends on: no declared dependencies. @@ -98,6 +116,7 @@ The structured visual model lives in [architecture.json](./architecture.json). I - `skill-manifest` evidence from `plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md`. - `skill-manifest` evidence from `plugins/apple-dev-skills/skills/explore-apple-swift-docs/SKILL.md`. - `skill-manifest` evidence from `plugins/apple-dev-skills/skills/format-swift-sources/SKILL.md`. +- `skill-manifest` evidence from `plugins/apple-dev-skills/skills/safari-extension-control-workflow/SKILL.md`. - `skill-manifest` evidence from `plugins/apple-dev-skills/skills/structure-swift-sources/SKILL.md`. - `skill-manifest` evidence from `plugins/apple-dev-skills/skills/swift-package-build-run-workflow/SKILL.md`. - `skill-manifest` evidence from `plugins/apple-dev-skills/skills/swift-package-testing-workflow/SKILL.md`. @@ -113,6 +132,18 @@ The structured visual model lives in [architecture.json](./architecture.json). I - `skill-manifest` evidence from `plugins/cardhop-app/skills/cardhop-contact-workflow/SKILL.md`. - `mcp-config` evidence from `plugins/cardhop-app/.mcp.json`. - `codex-plugin-manifest` evidence from `plugins/cardhop-app/.codex-plugin/plugin.json`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/aspnet-core-service-workflow/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/bootstrap-solution/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/build-csharp-project/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/build-fsharp-project/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/choose-project-shape/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/ci-workflow/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/diagnose-project/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/fsharp-csharp-interop/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/package-workflow/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/testing-workflow/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/tooling-style-workflow/SKILL.md`. +- `skill-manifest` evidence from `plugins/dotnet-skills/skills/upgrade-workflow/SKILL.md`. - `codex-plugin-manifest` evidence from `plugins/dotnet-skills/.codex-plugin/plugin.json`. - `skill-manifest` evidence from `plugins/productivity-skills/skills/explain-code-slice/SKILL.md`. - `skill-manifest` evidence from `plugins/productivity-skills/skills/maintain-project-accessibility/SKILL.md`. @@ -127,7 +158,12 @@ The structured visual model lives in [architecture.json](./architecture.json). I - `skill-manifest` evidence from `plugins/python-skills/skills/bootstrap-python-mcp-service/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/bootstrap-python-service/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/bootstrap-uv-python-workspace/SKILL.md`. +- `skill-manifest` evidence from `plugins/python-skills/skills/build-python-project/SKILL.md`. +- `skill-manifest` evidence from `plugins/python-skills/skills/choose-python-project-shape/SKILL.md`. +- `skill-manifest` evidence from `plugins/python-skills/skills/diagnose-python-project/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md`. +- `skill-manifest` evidence from `plugins/python-skills/skills/python-package-workflow/SKILL.md`. +- `skill-manifest` evidence from `plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/uv-pytest-unit-testing/SKILL.md`. - `codex-plugin-manifest` evidence from `plugins/python-skills/.codex-plugin/plugin.json`. - `codex-plugin-manifest` evidence from `plugins/rust-skills/.codex-plugin/plugin.json`. diff --git a/docs/architecture/architecture.json b/docs/architecture/architecture.json index b79ea2a2..51b4eb2a 100644 --- a/docs/architecture/architecture.json +++ b/docs/architecture/architecture.json @@ -1,5 +1,5 @@ { - "detectedAt": "2026-05-05T00:41:53.011781+00:00", + "detectedAt": "2026-05-14T23:00:09.343443+00:00", "detectionSource": "plugin-repo", "evidence": [ { @@ -38,6 +38,10 @@ "kind": "skill-manifest", "path": "plugins/apple-dev-skills/skills/format-swift-sources/SKILL.md" }, + { + "kind": "skill-manifest", + "path": "plugins/apple-dev-skills/skills/safari-extension-control-workflow/SKILL.md" + }, { "kind": "skill-manifest", "path": "plugins/apple-dev-skills/skills/structure-swift-sources/SKILL.md" @@ -98,6 +102,54 @@ "kind": "codex-plugin-manifest", "path": "plugins/cardhop-app/.codex-plugin/plugin.json" }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/aspnet-core-service-workflow/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/bootstrap-solution/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/build-csharp-project/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/build-fsharp-project/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/choose-project-shape/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/ci-workflow/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/diagnose-project/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/fsharp-csharp-interop/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/package-workflow/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/testing-workflow/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/tooling-style-workflow/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/upgrade-workflow/SKILL.md" + }, { "kind": "codex-plugin-manifest", "path": "plugins/dotnet-skills/.codex-plugin/plugin.json" @@ -154,10 +206,30 @@ "kind": "skill-manifest", "path": "plugins/python-skills/skills/bootstrap-uv-python-workspace/SKILL.md" }, + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/build-python-project/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/choose-python-project-shape/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/diagnose-python-project/SKILL.md" + }, { "kind": "skill-manifest", "path": "plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md" }, + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-package-workflow/SKILL.md" + }, + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md" + }, { "kind": "skill-manifest", "path": "plugins/python-skills/skills/uv-pytest-unit-testing/SKILL.md" @@ -283,7 +355,9 @@ "kind": "codex-plugin", "name": "dotnet-skills", "path": "plugins/dotnet-skills", - "targets": [] + "targets": [ + "skills:plugins/dotnet-skills/skills" + ] }, { "evidence": [ @@ -416,7 +490,7 @@ "targets": [] } ], - "projectRoot": "/Users/galew/Workspace/gaelic-ghost/socket", + "projectRoot": "/Users/galew/Workspace/gaelic-ghost/socket-wt-python-skills-gap-analysis", "relationships": [ { "evidence": [ @@ -514,6 +588,18 @@ "label": "plugin exposes skill", "to": "target:skill:apple-dev-skills/format-swift-sources" }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/apple-dev-skills/skills/safari-extension-control-workflow/SKILL.md" + } + ], + "from": "product:apple-dev-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:apple-dev-skills/safari-extension-control-workflow" + }, { "evidence": [ { @@ -670,6 +756,150 @@ "label": "plugin declares MCP servers", "to": "target:mcp:plugins/cardhop-app/.mcp.json" }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/aspnet-core-service-workflow/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/aspnet-core-service-workflow" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/bootstrap-solution/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/bootstrap-solution" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/build-csharp-project/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/build-csharp-project" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/build-fsharp-project/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/build-fsharp-project" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/choose-project-shape/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/choose-project-shape" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/ci-workflow/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/ci-workflow" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/diagnose-project/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/diagnose-project" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/fsharp-csharp-interop/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/fsharp-csharp-interop" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/package-workflow/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/package-workflow" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/testing-workflow/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/testing-workflow" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/tooling-style-workflow/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/tooling-style-workflow" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/dotnet-skills/skills/upgrade-workflow/SKILL.md" + } + ], + "from": "product:dotnet-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:dotnet-skills/upgrade-workflow" + }, { "evidence": [ { @@ -814,6 +1044,42 @@ "label": "plugin exposes skill", "to": "target:skill:python-skills/bootstrap-uv-python-workspace" }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/python-skills/skills/build-python-project/SKILL.md" + } + ], + "from": "product:python-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:python-skills/build-python-project" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/python-skills/skills/choose-python-project-shape/SKILL.md" + } + ], + "from": "product:python-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:python-skills/choose-python-project-shape" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/python-skills/skills/diagnose-python-project/SKILL.md" + } + ], + "from": "product:python-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:python-skills/diagnose-python-project" + }, { "evidence": [ { @@ -826,6 +1092,30 @@ "label": "plugin exposes skill", "to": "target:skill:python-skills/integrate-fastapi-fastmcp" }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/python-skills/skills/python-package-workflow/SKILL.md" + } + ], + "from": "product:python-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:python-skills/python-package-workflow" + }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md" + } + ], + "from": "product:python-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:python-skills/python-tooling-style-workflow" + }, { "evidence": [ { @@ -1322,6 +1612,18 @@ "name": "skill:apple-dev-skills/format-swift-sources", "path": "plugins/apple-dev-skills/skills/format-swift-sources/SKILL.md" }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/apple-dev-skills/skills/safari-extension-control-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:apple-dev-skills/safari-extension-control-workflow", + "path": "plugins/apple-dev-skills/skills/safari-extension-control-workflow/SKILL.md" + }, { "dependencies": [], "evidence": [ @@ -1478,6 +1780,150 @@ "name": "mcp:plugins/cardhop-app/.mcp.json", "path": "plugins/cardhop-app/.mcp.json" }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/aspnet-core-service-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/aspnet-core-service-workflow", + "path": "plugins/dotnet-skills/skills/aspnet-core-service-workflow/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/bootstrap-solution/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/bootstrap-solution", + "path": "plugins/dotnet-skills/skills/bootstrap-solution/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/build-csharp-project/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/build-csharp-project", + "path": "plugins/dotnet-skills/skills/build-csharp-project/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/build-fsharp-project/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/build-fsharp-project", + "path": "plugins/dotnet-skills/skills/build-fsharp-project/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/choose-project-shape/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/choose-project-shape", + "path": "plugins/dotnet-skills/skills/choose-project-shape/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/ci-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/ci-workflow", + "path": "plugins/dotnet-skills/skills/ci-workflow/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/diagnose-project/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/diagnose-project", + "path": "plugins/dotnet-skills/skills/diagnose-project/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/fsharp-csharp-interop/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/fsharp-csharp-interop", + "path": "plugins/dotnet-skills/skills/fsharp-csharp-interop/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/package-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/package-workflow", + "path": "plugins/dotnet-skills/skills/package-workflow/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/testing-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/testing-workflow", + "path": "plugins/dotnet-skills/skills/testing-workflow/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/tooling-style-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/tooling-style-workflow", + "path": "plugins/dotnet-skills/skills/tooling-style-workflow/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/dotnet-skills/skills/upgrade-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:dotnet-skills/upgrade-workflow", + "path": "plugins/dotnet-skills/skills/upgrade-workflow/SKILL.md" + }, { "dependencies": [], "evidence": [ @@ -1622,6 +2068,42 @@ "name": "skill:python-skills/bootstrap-uv-python-workspace", "path": "plugins/python-skills/skills/bootstrap-uv-python-workspace/SKILL.md" }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/build-python-project/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:python-skills/build-python-project", + "path": "plugins/python-skills/skills/build-python-project/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/choose-python-project-shape/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:python-skills/choose-python-project-shape", + "path": "plugins/python-skills/skills/choose-python-project-shape/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/diagnose-python-project/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:python-skills/diagnose-python-project", + "path": "plugins/python-skills/skills/diagnose-python-project/SKILL.md" + }, { "dependencies": [], "evidence": [ @@ -1634,6 +2116,30 @@ "name": "skill:python-skills/integrate-fastapi-fastmcp", "path": "plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md" }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-package-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:python-skills/python-package-workflow", + "path": "plugins/python-skills/skills/python-package-workflow/SKILL.md" + }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:python-skills/python-tooling-style-workflow", + "path": "plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md" + }, { "dependencies": [], "evidence": [ diff --git a/docs/maintainers/python-skills-plugin-plan.md b/docs/maintainers/python-skills-plugin-plan.md index 9ebe922a..f78c8c8a 100644 --- a/docs/maintainers/python-skills-plugin-plan.md +++ b/docs/maintainers/python-skills-plugin-plan.md @@ -231,12 +231,12 @@ The first slice should repair the current child contract and add the core missin - [x] Fix `plugins/python-skills/scripts/validate_repo_metadata.py` so it validates the child `AGENTS.md`, plugin manifest, and skill metadata without expecting a removed child `README.md`. - [x] Update child tests so they assert the current no-child-README contract. - [x] Record this expansion plan. -- [ ] Add `python-skills:choose-python-project-shape`. -- [ ] Add `python-skills:build-python-project`. -- [ ] Add `python-skills:diagnose-python-project`. -- [ ] Add `python-skills:python-package-workflow`. -- [ ] Add `python-skills:python-tooling-style-workflow`. -- [ ] Update `plugins/python-skills/.codex-plugin/plugin.json` default prompts and long description after the new skills exist. +- [x] Add `python-skills:choose-python-project-shape`. +- [x] Add `python-skills:build-python-project`. +- [x] Add `python-skills:diagnose-python-project`. +- [x] Add `python-skills:python-package-workflow`. +- [x] Add `python-skills:python-tooling-style-workflow`. +- [x] Update `plugins/python-skills/.codex-plugin/plugin.json` default prompts and long description after the new skills exist. - [ ] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. - [ ] Run root Socket metadata validation with `uv run scripts/validate_socket_metadata.py`. @@ -294,9 +294,9 @@ The validator repair alone is a maintenance fix. Adding the new skill inventory The expansion is ready when: -- [ ] The child validator passes without requiring a child `README.md`. +- [x] The child validator passes without requiring a child `README.md`. - [ ] The plugin has a documented skill naming convention and expansion plan. -- [ ] The first new skill set covers project choice, implementation, diagnostics, packaging, and tooling/style alignment. +- [x] The first new skill set covers project choice, implementation, diagnostics, packaging, and tooling/style alignment. - [ ] The guidance consistently uses `uv` for Python command examples. - [ ] The guidance uses official documentation as the source of truth for Python packaging, `uv`, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. - [ ] Root Socket docs, plugin metadata, child validation, and root validation agree on the exported Python skill surface. diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json index 00b295bd..99bedb12 100644 --- a/plugins/python-skills/.codex-plugin/plugin.json +++ b/plugins/python-skills/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "python-skills", "version": "6.9.0", - "description": "Bundled Python-focused Codex skills for uv bootstrapping, FastAPI and FastMCP scaffolding, FastAPI/FastMCP integration, and pytest workflows.", + "description": "Bundled Python-focused Codex skills for uv bootstrapping, project implementation, diagnostics, packaging, tooling, FastAPI, FastMCP, and pytest workflows.", "author": { "name": "Gale", "email": "mail@galewilliams.com", @@ -18,15 +18,18 @@ "fastapi", "fastmcp", "pytest", - "integration" + "integration", + "packaging", + "diagnostics", + "tooling" ], "skills": "./skills/", "interface": { "displayName": "Python Skills", - "shortDescription": "Python bootstrap, integration, scaffold, and pytest workflows for Codex.", - "longDescription": "Bundle reusable Codex skills for uv project bootstrapping, FastAPI and FastMCP service scaffolding, FastAPI/FastMCP integration work, and pytest setup in Python repositories.", + "shortDescription": "Python project, uv, FastAPI, FastMCP, pytest, packaging, and tooling workflows for Codex.", + "longDescription": "Bundle reusable Codex skills for choosing Python project shapes, building uv-managed Python projects, diagnosing Python failures, validating package surfaces, aligning tooling, bootstrapping FastAPI and FastMCP services, integrating FastAPI/FastMCP apps, and setting up pytest workflows.", "developerName": "gaelic-ghost", - "category": "Productivity", + "category": "Developer Tools", "capabilities": [ "Read", "Write" @@ -34,6 +37,11 @@ "websiteURL": "https://github.com/gaelic-ghost/python-skills", "defaultPrompt": [ "Bootstrap a new uv FastAPI service with typed settings and a committed .env baseline.", + "Choose the right Python project shape before we start implementing.", + "Build this Python project while respecting its uv, package layout, tests, Ruff, and mypy conventions.", + "Diagnose why this Python uv, import, pytest, Ruff, mypy, FastAPI, FastMCP, or package command failed.", + "Validate this Python package surface without publishing it.", + "Align this Python repo's uv, Ruff, mypy, pytest, dependency-group, and validation workflow.", "Set up pytest defaults for this uv workspace and show the right package-targeted test commands.", "Add a FastMCP surface to an existing FastAPI project and choose the right combined-app pattern." ], diff --git a/plugins/python-skills/skills/build-python-project/SKILL.md b/plugins/python-skills/skills/build-python-project/SKILL.md new file mode 100644 index 00000000..f76f5c02 --- /dev/null +++ b/plugins/python-skills/skills/build-python-project/SKILL.md @@ -0,0 +1,124 @@ +--- +name: build-python-project +description: Build or modify idiomatic Python projects using uv, explicit package layout, typed configuration, focused tests, Ruff, mypy, and repo-local validation without overriding established conventions. +license: Apache-2.0 +compatibility: Designed for Codex and compatible Agent Skills clients implementing Python changes in uv-managed projects, packages, CLIs, FastAPI services, FastMCP servers, and workspaces. +metadata: + owner: gaelic-ghost + repo: python-skills + category: python-implementation +allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*) +--- + +# Build Python Project + +## Purpose + +Implement or modify a Python project in the repository's own shape. + +The practical goal is clear package boundaries, readable data flow, typed configuration where the repo uses it, tests around changed behavior, and validation through the repo's `uv` commands. + +## When To Use + +- Use this skill when adding or changing Python source in an existing project. +- Use this skill when the project shape is already known or was chosen with `choose-python-project-shape`. +- Use this skill when implementation touches reusable package code, CLI code, FastAPI adapters, FastMCP adapters, or shared domain logic. +- Use a more specific workflow when the task is only test setup, packaging, diagnostics, tooling, or FastAPI/FastMCP integration. + +## Source Check + +Use official documentation first when implementation depends on package, tool, or framework behavior: + +- [uv documentation](https://docs.astral.sh/uv/) +- [Python packaging user guide](https://packaging.python.org/) +- [FastAPI documentation](https://fastapi.tiangolo.com/) +- [FastMCP documentation](https://gofastmcp.com/getting-started/welcome) +- [pytest documentation](https://docs.pytest.org/en/stable/) +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [mypy documentation](https://mypy.readthedocs.io/en/stable/) + +## Implementation Workflow + +1. Inspect project shape: + ```bash + rg --files -g 'pyproject.toml' -g 'uv.lock' -g '*.py' -g 'tests/**/*.py' -g '.python-version' + ``` +2. Read the relevant `pyproject.toml` sections: + - `[project]` + - `[tool.uv]` + - `[tool.uv.workspace]` + - `[dependency-groups]` + - `[tool.pytest.ini_options]` + - `[tool.ruff]` + - `[tool.mypy]` +3. Identify the behavior being changed and who calls it next. +4. Keep reusable logic separate from framework adapters when the behavior is not inherently tied to FastAPI, FastMCP, or a CLI parser. +5. Prefer explicit inputs and outputs for transformations. +6. Keep environment reads, network calls, file IO, process exits, and framework globals at the edge of the workflow. +7. Add or update tests around the changed behavior. +8. Run the narrowest useful validation first, then broaden before a checkpoint when risk warrants it. + +## Package And Module Shape + +Respect the existing layout first. + +For `src/` layouts: + +- import through the installed package name +- avoid test-only import hacks +- keep package-private modules clearly internal by name or documentation + +For flat layouts: + +- avoid introducing a second package root casually +- use local conventions for imports and tests +- consider a package layout only when packaging or import correctness is already part of the task + +For workspaces: + +- use `uv run --package ` when commands need a specific member +- keep local package dependencies expressed through workspace sources +- avoid copying shared code between members + +## Configuration + +When generated or existing projects use `pydantic-settings`, keep committed `.env` files limited to safe defaults and keep `.env.local` or real secret stores for machine-local and secret values. + +For tests, override environment variables or settings dependencies rather than mutating committed `.env` files. + +## Validation + +Choose commands based on the changed surface: + +```bash +uv run pytest +uv run ruff check . +uv run mypy . +``` + +Use package targeting for workspaces: + +```bash +uv run --package pytest +uv run --package mypy . +``` + +Run `uv sync --dev` first when dependency resolution, lockfiles, or Python versions changed. + +## Output Shape + +Return: + +1. `Changed behavior`: what user-visible or package-visible behavior changed. +2. `Files`: key files changed. +3. `Tests`: tests added or updated. +4. `Validation`: exact commands run and results. +5. `Residual risk`: anything not covered. + +## Guardrails + +- Do not add a new framework, queue, service object, repository layer, or dependency without naming the concrete need it solves. +- Do not mix broad formatting sweeps into behavior changes. +- Do not hide import errors with `sys.path` edits unless the repo already uses that pattern and the reason is documented. +- Do not add machine-local paths to `pyproject.toml`, lockfiles, CI, or docs. +- Do not silently skip tests when the changed behavior is testable. diff --git a/plugins/python-skills/skills/build-python-project/agents/openai.yaml b/plugins/python-skills/skills/build-python-project/agents/openai.yaml new file mode 100644 index 00000000..528d1462 --- /dev/null +++ b/plugins/python-skills/skills/build-python-project/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Build Python Project" + short_description: "Implement Python changes with uv, tests, package layout, Ruff, and mypy." + brand_color: "#0F766E" + default_prompt: "Use $build-python-project to inspect the existing Python project shape, implement the requested behavior in the repo's own style, add focused tests, and validate with the narrowest useful uv commands." + +policy: + allow_implicit_invocation: true diff --git a/plugins/python-skills/skills/choose-python-project-shape/SKILL.md b/plugins/python-skills/skills/choose-python-project-shape/SKILL.md new file mode 100644 index 00000000..3512cc90 --- /dev/null +++ b/plugins/python-skills/skills/choose-python-project-shape/SKILL.md @@ -0,0 +1,111 @@ +--- +name: choose-python-project-shape +description: Choose the right Python project shape before implementation, including uv project versus workspace layout, package, CLI, FastAPI, FastMCP, testing, packaging, tooling, and validation boundaries. +license: Apache-2.0 +compatibility: Designed for Codex and compatible Agent Skills clients working with Python, uv-managed projects, FastAPI, FastMCP, pytest, Ruff, mypy, and Python packaging workflows. +metadata: + owner: gaelic-ghost + repo: python-skills + category: python-planning +allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*) +--- + +# Choose Python Project Shape + +## Purpose + +Pick the smallest correct Python project shape before code changes begin. + +The practical decision is what kind of Python surface the user needs, whether it should be a single `uv` project or workspace, which package or service owns the behavior, which validation commands should prove the work, and where package, API, MCP, test, or tooling boundaries should sit. + +## When To Use + +- Use this skill when the user wants a new Python project but has not chosen package, app, service, MCP server, workspace, or tooling shape. +- Use this skill before scaffolding with `bootstrap-uv-python-workspace`, `bootstrap-python-service`, or `bootstrap-python-mcp-service`. +- Use this skill when an existing repository has Python files and the next change could cross package, service, test, or tooling boundaries. +- Use this skill when the user asks whether Python, FastAPI, FastMCP, a CLI, or a package is the right shape for the work. + +## Source Check + +Use official documentation first before making claims about Python packaging, `uv`, FastAPI, FastMCP, tests, linting, or typing: + +- [uv documentation](https://docs.astral.sh/uv/) +- [Python packaging user guide](https://packaging.python.org/) +- [Writing `pyproject.toml`](https://packaging.python.org/guides/writing-pyproject-toml/) +- [FastAPI documentation](https://fastapi.tiangolo.com/) +- [FastMCP documentation](https://gofastmcp.com/getting-started/welcome) +- [pytest documentation](https://docs.pytest.org/en/stable/) +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [mypy documentation](https://mypy.readthedocs.io/en/stable/) + +Translate any documentation rule into the concrete repository decision it changes. + +## Classification Workflow + +1. Inspect the repository shape: + ```bash + rg --files -g 'pyproject.toml' -g 'uv.lock' -g 'requirements*.txt' -g 'setup.py' -g 'setup.cfg' -g 'tox.ini' -g 'noxfile.py' -g '.python-version' -g '.github/workflows/*.yml' -g '.github/workflows/*.yaml' + ``` +2. Identify the user-visible job: + - reusable package + - command-line app + - FastAPI service + - FastMCP server + - combined FastAPI and FastMCP app + - test or tooling setup + - package maintenance + - CI maintenance + - dependency or Python-version upgrade + - Python member inside a mixed-language repository +3. Choose the project layout: + - single `uv` project for one small package, CLI, service, or MCP server + - `uv` workspace when multiple packages or services need shared local dependencies + - package plus tests when the repo exposes reusable logic + - service plus shared package when API or MCP adapters should stay thin around reusable behavior + - tooling-only change when the code shape already fits +4. Choose the validation path: + - `uv sync --dev` when dependency resolution matters + - `uv run pytest` for behavior + - `uv run ruff check .` for lint + - `uv run ruff format --check .` only when formatting is enforced + - `uv run mypy .` when type checking is configured + - package build checks only when package metadata or release surfaces changed +5. Choose the next skill: + - scaffold: `bootstrap-uv-python-workspace`, `bootstrap-python-service`, or `bootstrap-python-mcp-service` + - implementation: `build-python-project` + - test work: `uv-pytest-unit-testing` + - FastAPI/FastMCP integration: `integrate-fastapi-fastmcp` + - diagnosis: `diagnose-python-project` + - package validation: `python-package-workflow` + - tooling alignment: `python-tooling-style-workflow` + +## Recommendations + +Prefer `uv` as the command and dependency surface. + +Prefer `pyproject.toml` as the project metadata and tool configuration home unless the repository already uses dedicated config files for a clear reason. + +Use a `src/` layout when creating reusable packages or packages that need import behavior to match installed use. Preserve an existing flat layout unless the requested work already requires a package-structure cleanup. + +Keep FastAPI and FastMCP adapter code thin around shared logic when the behavior should be reusable outside the web or MCP transport. + +Use a workspace only when multiple packages or services need a real local package relationship. Do not add a workspace for a single small project that can stay simpler. + +## Output Shape + +Return: + +1. `Shape`: selected package, CLI, service, MCP server, workspace, tooling, package, CI, or upgrade shape. +2. `Why`: concrete user-visible reason. +3. `Layout`: expected files or package members. +4. `Next skill`: the skill that should handle implementation. +5. `Validation`: exact `uv` commands to prove the next change. +6. `Docs`: docs or repo guidance that should change. + +## Guardrails + +- Do not scaffold before the project shape is clear. +- Do not create a workspace just to look organized. +- Do not introduce machine-local dependency paths into shared project files. +- Do not publish packages, open releases, or change CI secrets from this planning skill. +- Do not replace established repo conventions unless the current shape blocks the requested work. diff --git a/plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml b/plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml new file mode 100644 index 00000000..61beda80 --- /dev/null +++ b/plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Choose Python Project Shape" + short_description: "Choose Python package, service, MCP, workspace, test, tooling, package, CI, or upgrade shape." + brand_color: "#2563EB" + default_prompt: "Use $choose-python-project-shape to inspect this repository, choose the smallest correct Python project shape, recommend the next Python skill, and return exact uv validation commands before implementation starts." + +policy: + allow_implicit_invocation: true diff --git a/plugins/python-skills/skills/diagnose-python-project/SKILL.md b/plugins/python-skills/skills/diagnose-python-project/SKILL.md new file mode 100644 index 00000000..ab76fd79 --- /dev/null +++ b/plugins/python-skills/skills/diagnose-python-project/SKILL.md @@ -0,0 +1,123 @@ +--- +name: diagnose-python-project +description: Diagnose Python uv sync, lock, import, test, Ruff, mypy, FastAPI, FastMCP, packaging, and CI failures with concrete phase classification and next checks. +license: Apache-2.0 +compatibility: Designed for Codex and compatible Agent Skills clients diagnosing Python projects that use uv, pytest, Ruff, mypy, FastAPI, FastMCP, and Python package metadata. +metadata: + owner: gaelic-ghost + repo: python-skills + category: python-diagnostics +allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*) +--- + +# Diagnose Python Project + +## Purpose + +Find the first meaningful cause of a Python failure and explain it in human terms. + +The useful answer is not "tests failed." It is what command failed, which project or package failed, which phase failed, why it most likely failed, and the smallest next check or fix. + +## When To Use + +- Use this skill when `uv sync`, `uv run pytest`, `uv run ruff`, `uv run mypy`, package build checks, FastAPI startup, or FastMCP startup fails. +- Use this skill when Python version selection, dependency groups, lockfiles, package layout, imports, test discovery, or type checking are unclear. +- Use this skill before widening into refactors after a vague Python error. + +## Source Check + +Use official documentation first: + +- [uv documentation](https://docs.astral.sh/uv/) +- [pytest documentation](https://docs.pytest.org/en/stable/) +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [mypy documentation](https://mypy.readthedocs.io/en/stable/) +- [Python packaging user guide](https://packaging.python.org/) +- [FastAPI documentation](https://fastapi.tiangolo.com/) +- [FastMCP documentation](https://gofastmcp.com/getting-started/welcome) + +## Diagnostic Workflow + +1. Capture repository shape: + ```bash + rg --files -g 'pyproject.toml' -g 'uv.lock' -g '.python-version' -g 'requirements*.txt' -g 'setup.py' -g 'setup.cfg' -g 'tox.ini' -g 'noxfile.py' -g '*.py' + ``` +2. Identify the exact failing command. +3. Re-run only the narrowest failing command when reproduction is needed. +4. Classify the failure phase: + - Python version + - dependency resolution + - lockfile sync + - import or package layout + - test discovery + - test execution + - lint + - format + - type check + - FastAPI startup + - FastMCP startup + - package build + - CI environment +5. Identify the first meaningful error. +6. Explain the likely cause and smallest next check. + +## Common Failure Classes + +### Python Version + +Look for `requires-python`, `.python-version`, CI setup, and `uv` interpreter selection. + +Report when the repo asks for a Python version that local or CI does not provide. + +### Dependency Resolution + +Look for dependency groups, optional dependencies, extras, index configuration, lockfile drift, and private package sources. + +Do not turn authenticated index failures into generic network diagnoses. Name the package source or credential surface when visible. + +### Imports And Package Layout + +Separate installed-package import failures from test-context import failures. + +For `src/` layouts, check whether commands run through `uv` with the package installed. For workspaces, check whether the command targets the intended package member. + +### Test Discovery And Execution + +Discovery failures usually point at package imports, pytest configuration, plugin availability, markers, or test file naming. + +Execution failures usually point at behavior, fixtures, environment, timing, async boundaries, or external dependencies. + +### Ruff + +Separate lint failures from format failures. + +Use `uv run ruff check .` for lint and `uv run ruff format --check .` only when the repo enforces formatting. + +### mypy + +Check configuration scope, missing stubs, optional dependencies, package exports, and Python-version settings before suppressing errors. + +### FastAPI And FastMCP + +Check import paths, app object names, lifespan handling, settings loading, dependency initialization, and environment variables. + +For combined FastAPI/FastMCP apps, verify that mounted app lifespan behavior was preserved. + +## Output Shape + +Return: + +1. `Command`: exact failing command. +2. `Phase`: failure phase. +3. `Project`: package, workspace member, app, or workflow involved. +4. `First meaningful error`: short quoted or paraphrased error. +5. `Likely cause`: concrete explanation. +6. `Next check`: one or two smallest useful commands or edits. + +## Guardrails + +- Do not bury the first meaningful error under a long transcript. +- Do not rerun broad commands repeatedly before narrowing the phase. +- Do not delete lockfiles, virtual environments, caches, or generated artifacts without explaining why and getting approval when destructive. +- Do not add `sys.path` hacks to hide package-layout problems. +- Do not suppress Ruff or mypy findings to make checks pass unless the suppression is intentional and documented. diff --git a/plugins/python-skills/skills/diagnose-python-project/agents/openai.yaml b/plugins/python-skills/skills/diagnose-python-project/agents/openai.yaml new file mode 100644 index 00000000..d08dca2b --- /dev/null +++ b/plugins/python-skills/skills/diagnose-python-project/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Diagnose Python Project" + short_description: "Diagnose uv, import, pytest, Ruff, mypy, FastAPI, FastMCP, and package failures." + brand_color: "#B45309" + default_prompt: "Use $diagnose-python-project to classify the failing Python command by phase, identify the first meaningful error, explain the likely cause, and return the smallest useful next check or fix." + +policy: + allow_implicit_invocation: true diff --git a/plugins/python-skills/skills/python-package-workflow/SKILL.md b/plugins/python-skills/skills/python-package-workflow/SKILL.md new file mode 100644 index 00000000..0b376f33 --- /dev/null +++ b/plugins/python-skills/skills/python-package-workflow/SKILL.md @@ -0,0 +1,119 @@ +--- +name: python-package-workflow +description: Validate Python package surfaces with pyproject metadata, uv-managed builds, dependency boundaries, local smoke checks, semantic versioning, and release-boundary guidance. +license: Apache-2.0 +compatibility: Designed for Codex and compatible Agent Skills clients maintaining Python packages with uv, pyproject.toml, build metadata, tests, and package release preparation. +metadata: + owner: gaelic-ghost + repo: python-skills + category: python-packaging +allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*) +--- + +# Python Package Workflow + +## Purpose + +Validate a Python package before release or publication. + +The practical job is to make package metadata explicit, build and test the package, inspect the generated artifact when needed, and keep publishing as an explicit release step rather than an accidental side effect. + +## When To Use + +- Use this skill when a Python library is intended to become an installable package. +- Use this skill when `pyproject.toml` package metadata, versioning, dependencies, optional dependencies, or release notes change. +- Use this skill when adding package validation to CI. +- Use this skill before package publication, but do not publish unless the user asks for that release step. + +## Source Check + +Use official documentation first: + +- [Python packaging user guide](https://packaging.python.org/) +- [Writing `pyproject.toml`](https://packaging.python.org/guides/writing-pyproject-toml/) +- [uv build documentation](https://docs.astral.sh/uv/concepts/projects/build/) +- [Python package version specifiers](https://packaging.python.org/specifications/version-specifiers/) + +Translate documentation into the specific package, metadata, and release decision in front of you. + +## Inspection Workflow + +1. Identify package-bearing projects: + ```bash + rg --files -g 'pyproject.toml' -g 'uv.lock' -g 'README*' -g 'LICENSE*' -g 'src/**/*.py' -g '*.py' + ``` +2. Confirm the intended package boundary: + - one package per public library project + - no accidental service-only package release + - no hidden machine-local dependencies + - workspace members packaged only when they are intended package surfaces +3. Check metadata: + - `name` + - `version` or repository-owned version source + - `description` + - `readme` + - `requires-python` + - `license` + - `authors` or maintainers + - `classifiers` + - `dependencies` + - optional dependencies + - project URLs + - build system +4. Check dependency boundaries: + - runtime dependencies in `[project].dependencies` + - optional feature dependencies in `[project.optional-dependencies]` + - maintainer tools in `[dependency-groups]` + - workspace sources in `[tool.uv.sources]` +5. Run validation: + ```bash + uv sync --dev + uv run pytest + uv run ruff check . + uv run mypy . + uv build + ``` +6. Inspect generated package output when metadata or package contents changed. + +## Workspace Notes + +For workspaces, validate package members deliberately: + +```bash +uv run --package pytest +uv build --package +``` + +Do not assume every workspace member should publish. Services, examples, internal tools, and test fixtures are often intentionally unpublished. + +## Local Smoke Checks + +When package behavior is public or packaging changed materially, create a temporary consumer outside the package tree and install the built artifact there. + +Keep the smoke check small: + +- install the built wheel +- import the public package +- call one tiny public function or CLI entry point +- confirm package metadata when relevant + +Do not commit temporary consumer directories or generated artifacts unless the repo intentionally tracks release evidence. + +## Output Shape + +Return: + +1. `Package boundary`: package name and path. +2. `Metadata`: changed or verified package metadata. +3. `Artifacts`: built wheel or sdist path if created. +4. `Validation`: exact commands run and results. +5. `Publish status`: not published, blocked, or explicitly published by user request. +6. `Residual risk`: missing smoke checks, external index state, or release notes still needed. + +## Guardrails + +- Do not publish to PyPI or another index unless the user explicitly asks for publication. +- Do not add machine-local paths to package metadata, dependencies, lockfiles, docs, examples, or CI. +- Do not move maintainer tools into runtime dependencies. +- Do not package app-only or service-only code accidentally. +- Do not change semantic versioning without checking repo-local release policy. diff --git a/plugins/python-skills/skills/python-package-workflow/agents/openai.yaml b/plugins/python-skills/skills/python-package-workflow/agents/openai.yaml new file mode 100644 index 00000000..08398366 --- /dev/null +++ b/plugins/python-skills/skills/python-package-workflow/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Python Package Workflow" + short_description: "Validate Python package metadata, builds, artifacts, and release boundaries." + brand_color: "#7C3AED" + default_prompt: "Use $python-package-workflow to inspect pyproject package metadata, validate dependency boundaries, build the package with uv when appropriate, run local smoke checks, and avoid publishing unless explicitly requested." + +policy: + allow_implicit_invocation: true diff --git a/plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md b/plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md new file mode 100644 index 00000000..f174c9bd --- /dev/null +++ b/plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md @@ -0,0 +1,133 @@ +--- +name: python-tooling-style-workflow +description: Align Python formatting, linting, type checking, pytest configuration, dependency groups, local tooling, and CI validation around uv without overriding repo-local conventions. +license: Apache-2.0 +compatibility: Designed for Codex and compatible Agent Skills clients maintaining Python tooling with uv, Ruff, mypy, pytest, pyproject.toml, and optional CI integration. +metadata: + owner: gaelic-ghost + repo: python-skills + category: python-tooling +allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*) +--- + +# Python Tooling And Style Workflow + +## Purpose + +Keep Python formatting, linting, type checking, and test tooling explicit. + +The practical job is to respect existing repo conventions, use `uv` for commands and dependency groups, keep Ruff and mypy behavior understandable, and make local validation match CI. + +## When To Use + +- Use this skill when adding or changing Ruff, mypy, pytest, dependency groups, or Python tooling config. +- Use this skill when local validation and CI disagree. +- Use this skill when style drift causes noisy diffs. +- Use this skill when a repository needs one documented Python validation story. + +## Source Check + +Use official documentation first: + +- [uv documentation](https://docs.astral.sh/uv/) +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [mypy documentation](https://mypy.readthedocs.io/en/stable/) +- [pytest documentation](https://docs.pytest.org/en/stable/) +- [Writing `pyproject.toml`](https://packaging.python.org/guides/writing-pyproject-toml/) + +## Inspection Workflow + +1. Inspect tooling files: + ```bash + rg --files -g 'pyproject.toml' -g 'uv.lock' -g 'ruff.toml' -g '.ruff.toml' -g 'mypy.ini' -g '.mypy.ini' -g 'pytest.ini' -g 'tox.ini' -g 'noxfile.py' -g '.pre-commit-config.yaml' -g '.github/workflows/*.yml' -g '.github/workflows/*.yaml' + ``` +2. Read existing repo guidance and CI. +3. Identify what is already enforced: + - `uv sync` + - `pytest` + - Ruff lint + - Ruff format + - mypy + - coverage + - pre-commit + - custom scripts +4. Decide the smallest alignment: + - document existing commands + - add missing dev dependency groups + - add or adjust Ruff config + - add or adjust mypy config + - register pytest markers + - align CI commands with local commands +5. Run validation. + +## Ruff Guidance + +Use Ruff lint checks for code-quality and style rules: + +```bash +uv run ruff check . +``` + +Use Ruff formatting only when the repo has adopted it or the user asked for formatting: + +```bash +uv run ruff format . +uv run ruff format --check . +``` + +Keep formatting-only sweeps separate from behavior changes when practical. + +## mypy Guidance + +Respect existing strictness first. + +When adding type-checking: + +- start with a clear package scope +- keep missing-stub decisions explicit +- avoid blanket ignores +- stage stricter settings when an existing codebase is noisy +- check Python-version settings against project metadata + +Do not suppress type errors to make a check pass unless the suppression is narrow and documented. + +## pytest Guidance + +Keep pytest configuration close to the repo's existing pattern. + +Use `pyproject.toml` for new configuration unless the repo already keeps pytest settings in a dedicated file. + +Register custom marks to avoid marker warnings, and keep fixtures scoped narrowly unless expensive setup requires a wider scope. + +## Dependency Groups + +Keep maintainer tools in dependency groups rather than runtime dependencies: + +```toml +[dependency-groups] +dev = [ + "pytest", + "ruff", + "mypy", +] +``` + +Use repo-local version bounds when the project already pins tooling. Do not introduce global-tool assumptions into docs or CI. + +## Output Shape + +Return: + +1. `Existing tooling`: pytest, Ruff, mypy, dependency groups, CI, and custom scripts. +2. `Change`: documentation, dependency, config, formatting, linting, typing, or CI alignment. +3. `Commands`: exact `uv` commands. +4. `Validation`: results from relevant checks. +5. `Residual risk`: anything still manual or intentionally unenforced. + +## Guardrails + +- Do not make broad formatting sweeps inside unrelated behavior changes. +- Do not turn every lint or type suggestion into a blocking rule at once. +- Do not move maintainer tools into runtime dependencies. +- Do not depend on globally installed Python tools. +- Do not add pre-commit, tox, nox, or CI complexity unless the repo or user needs that surface. diff --git a/plugins/python-skills/skills/python-tooling-style-workflow/agents/openai.yaml b/plugins/python-skills/skills/python-tooling-style-workflow/agents/openai.yaml new file mode 100644 index 00000000..092452c1 --- /dev/null +++ b/plugins/python-skills/skills/python-tooling-style-workflow/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Python Tooling And Style Workflow" + short_description: "Align uv, Ruff, mypy, pytest, dependency groups, and local validation." + brand_color: "#0891B2" + default_prompt: "Use $python-tooling-style-workflow to inspect existing Python tooling, align Ruff, mypy, pytest, dependency groups, and uv validation commands without overriding repo-local conventions." + +policy: + allow_implicit_invocation: true diff --git a/plugins/python-skills/tests/test_plugin_smoke.py b/plugins/python-skills/tests/test_plugin_smoke.py index 33e597ac..64e2e29c 100644 --- a/plugins/python-skills/tests/test_plugin_smoke.py +++ b/plugins/python-skills/tests/test_plugin_smoke.py @@ -34,7 +34,7 @@ def test_plugin_manifest_and_marketplace_contract() -> None: assert manifest["name"] == "python-skills" assert manifest["skills"] == "./skills/" assert manifest["interface"]["displayName"] == "Python Skills" - assert manifest["interface"]["category"] == "Productivity" + assert manifest["interface"]["category"] == "Developer Tools" assert ".codex-plugin/plugin.json" in agents_text assert "Root [`skills/`](./skills/) is the authored workflow surface" in agents_text From 38f9744ac483fcc89f10781b0cad827f363a8885 Mon Sep 17 00:00:00 2001 From: Gale W Date: Fri, 15 May 2026 11:30:15 -0400 Subject: [PATCH 3/6] plugin: add python ci and upgrade workflows --- README.md | 2 +- ROADMAP.md | 17 ++- TODO.md | 5 +- docs/architecture/ARCHITECTURE.md | 4 + docs/architecture/architecture.json | 58 +++++++- docs/maintainers/python-skills-plugin-plan.md | 19 +-- .../python-skills/.codex-plugin/plugin.json | 12 +- .../skills/python-ci-workflow/SKILL.md | 126 +++++++++++++++++ .../python-ci-workflow/agents/openai.yaml | 8 ++ .../skills/python-upgrade-workflow/SKILL.md | 129 ++++++++++++++++++ .../agents/openai.yaml | 8 ++ 11 files changed, 365 insertions(+), 23 deletions(-) create mode 100644 plugins/python-skills/skills/python-ci-workflow/SKILL.md create mode 100644 plugins/python-skills/skills/python-ci-workflow/agents/openai.yaml create mode 100644 plugins/python-skills/skills/python-upgrade-workflow/SKILL.md create mode 100644 plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml diff --git a/README.md b/README.md index 25e43155..c01d51cb 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ Current Socket catalog shape: - `cardhop-app`: mixed skill plus bundled MCP server for Cardhop.app contact workflows - `dotnet-skills`: .NET, F#, and C# project-shape, bootstrap, implementation, test, package, diagnostics, ASP.NET Core, interop, CI, upgrade, and tooling guidance - `productivity-skills`: general-purpose maintainer and documentation workflow baseline -- `python-skills`: Python, `uv`, project implementation, diagnostics, packaging, tooling, FastAPI, FastMCP, and pytest workflow plugin +- `python-skills`: Python, `uv`, project implementation, diagnostics, packaging, tooling, CI, upgrades, FastAPI, FastMCP, and pytest workflow plugin - `speak-swiftly`: Git-backed Speak Swiftly plugin from the standalone SpeakSwiftlyServer repository - `swiftasb-skills`: SwiftASB companion guidance - `things-app`: mixed skill plus bundled MCP server for Things.app workflows diff --git a/ROADMAP.md b/ROADMAP.md index 26e25304..58b3981a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -100,8 +100,8 @@ In Progress - [x] Repair the `python-skills` child validator so it matches the current monorepo-owned child docs model without reintroducing a child README. - [x] Record the detailed expansion plan in [`docs/maintainers/python-skills-plugin-plan.md`](./docs/maintainers/python-skills-plugin-plan.md). -- [x] Expand `python-skills` from scaffold-heavy coverage into ongoing project choice, implementation, diagnostics, packaging, and tooling/style workflows. -- [ ] Keep the existing `uv`, FastAPI, FastMCP, and pytest skill surfaces intact unless a later cleanup deliberately renames or replaces one without leaving duplicate long-term surfaces. +- [x] Expand `python-skills` from scaffold-heavy coverage into ongoing project choice, implementation, diagnostics, packaging, tooling/style, CI, and upgrade workflows. +- [x] Keep the existing `uv`, FastAPI, FastMCP, and pytest skill surfaces intact unless a later cleanup deliberately renames or replaces one without leaving duplicate long-term surfaces. ### Tickets @@ -111,16 +111,19 @@ In Progress - [x] Add `python-skills:diagnose-python-project`. - [x] Add `python-skills:python-package-workflow`. - [x] Add `python-skills:python-tooling-style-workflow`. +- [x] Add `python-skills:python-ci-workflow`. +- [x] Add `python-skills:python-upgrade-workflow`. +- [x] Keep `python-skills:uv-pytest-unit-testing` as the release-compatible pytest workflow name for now. - [x] Update Python plugin metadata after the first new skill slice lands. -- [ ] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. -- [ ] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. +- [x] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. +- [x] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. ### Exit Criteria - [x] The child validator passes without requiring a child `README.md`. -- [x] The Python skill inventory covers project choice, implementation, diagnostics, packaging, and tooling/style alignment in addition to existing scaffold, integration, and pytest workflows. -- [ ] The Python plugin guidance consistently uses `uv` for command examples and official documentation as the source of truth for Python packaging, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. -- [ ] Root Socket docs, marketplace wiring, child validation, and root validation agree on the exported Python skill surface. +- [x] The Python skill inventory covers project choice, implementation, diagnostics, packaging, tooling/style alignment, CI, and upgrades in addition to existing scaffold, integration, and pytest workflows. +- [x] The Python plugin guidance consistently uses `uv` for command examples and official documentation as the source of truth for Python packaging, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. +- [x] Root Socket docs, marketplace wiring, child validation, and root validation agree on the exported Python skill surface. ## Backlog Candidates diff --git a/TODO.md b/TODO.md index 537524d0..586283b9 100644 --- a/TODO.md +++ b/TODO.md @@ -42,8 +42,11 @@ This file is the Socket-level backlog for child plugins that no longer keep thei - [x] Add `diagnose-python-project`. - [x] Add `python-package-workflow`. - [x] Add `python-tooling-style-workflow`. +- [x] Add `python-ci-workflow`. +- [x] Add `python-upgrade-workflow`. +- [x] Keep `uv-pytest-unit-testing` as the release-compatible pytest workflow name for now. - [x] Update `plugins/python-skills/.codex-plugin/plugin.json` after the new skills exist. -- [ ] Confirm `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .` pass after skill or metadata changes. +- [x] Confirm `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .` pass after the second skill slice. ### swiftasb-skills diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 0ce8e073..44d8fe45 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -80,8 +80,10 @@ See [SLICES.md](./SLICES.md) for provable end-to-end code paths. - `skill:python-skills/choose-python-project-shape` (codex-skill) at `plugins/python-skills/skills/choose-python-project-shape/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/diagnose-python-project` (codex-skill) at `plugins/python-skills/skills/diagnose-python-project/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/integrate-fastapi-fastmcp` (codex-skill) at `plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md` depends on: no declared dependencies. +- `skill:python-skills/python-ci-workflow` (codex-skill) at `plugins/python-skills/skills/python-ci-workflow/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/python-package-workflow` (codex-skill) at `plugins/python-skills/skills/python-package-workflow/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/python-tooling-style-workflow` (codex-skill) at `plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md` depends on: no declared dependencies. +- `skill:python-skills/python-upgrade-workflow` (codex-skill) at `plugins/python-skills/skills/python-upgrade-workflow/SKILL.md` depends on: no declared dependencies. - `skill:python-skills/uv-pytest-unit-testing` (codex-skill) at `plugins/python-skills/skills/uv-pytest-unit-testing/SKILL.md` depends on: no declared dependencies. - `skill:swiftasb-skills/build-appkit-app` (codex-skill) at `plugins/swiftasb-skills/skills/build-appkit-app/SKILL.md` depends on: no declared dependencies. - `skill:swiftasb-skills/build-swift-package` (codex-skill) at `plugins/swiftasb-skills/skills/build-swift-package/SKILL.md` depends on: no declared dependencies. @@ -162,8 +164,10 @@ The structured visual model lives in [architecture.json](./architecture.json). I - `skill-manifest` evidence from `plugins/python-skills/skills/choose-python-project-shape/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/diagnose-python-project/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md`. +- `skill-manifest` evidence from `plugins/python-skills/skills/python-ci-workflow/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/python-package-workflow/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md`. +- `skill-manifest` evidence from `plugins/python-skills/skills/python-upgrade-workflow/SKILL.md`. - `skill-manifest` evidence from `plugins/python-skills/skills/uv-pytest-unit-testing/SKILL.md`. - `codex-plugin-manifest` evidence from `plugins/python-skills/.codex-plugin/plugin.json`. - `codex-plugin-manifest` evidence from `plugins/rust-skills/.codex-plugin/plugin.json`. diff --git a/docs/architecture/architecture.json b/docs/architecture/architecture.json index 51b4eb2a..60faaf5c 100644 --- a/docs/architecture/architecture.json +++ b/docs/architecture/architecture.json @@ -1,5 +1,5 @@ { - "detectedAt": "2026-05-14T23:00:09.343443+00:00", + "detectedAt": "2026-05-15T15:28:43.389437+00:00", "detectionSource": "plugin-repo", "evidence": [ { @@ -222,6 +222,10 @@ "kind": "skill-manifest", "path": "plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md" }, + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-ci-workflow/SKILL.md" + }, { "kind": "skill-manifest", "path": "plugins/python-skills/skills/python-package-workflow/SKILL.md" @@ -230,6 +234,10 @@ "kind": "skill-manifest", "path": "plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md" }, + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-upgrade-workflow/SKILL.md" + }, { "kind": "skill-manifest", "path": "plugins/python-skills/skills/uv-pytest-unit-testing/SKILL.md" @@ -1092,6 +1100,18 @@ "label": "plugin exposes skill", "to": "target:skill:python-skills/integrate-fastapi-fastmcp" }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/python-skills/skills/python-ci-workflow/SKILL.md" + } + ], + "from": "product:python-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:python-skills/python-ci-workflow" + }, { "evidence": [ { @@ -1116,6 +1136,18 @@ "label": "plugin exposes skill", "to": "target:skill:python-skills/python-tooling-style-workflow" }, + { + "evidence": [ + { + "kind": "skill-directory", + "path": "plugins/python-skills/skills/python-upgrade-workflow/SKILL.md" + } + ], + "from": "product:python-skills", + "kind": "exposes", + "label": "plugin exposes skill", + "to": "target:skill:python-skills/python-upgrade-workflow" + }, { "evidence": [ { @@ -2116,6 +2148,18 @@ "name": "skill:python-skills/integrate-fastapi-fastmcp", "path": "plugins/python-skills/skills/integrate-fastapi-fastmcp/SKILL.md" }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-ci-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:python-skills/python-ci-workflow", + "path": "plugins/python-skills/skills/python-ci-workflow/SKILL.md" + }, { "dependencies": [], "evidence": [ @@ -2140,6 +2184,18 @@ "name": "skill:python-skills/python-tooling-style-workflow", "path": "plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md" }, + { + "dependencies": [], + "evidence": [ + { + "kind": "skill-manifest", + "path": "plugins/python-skills/skills/python-upgrade-workflow/SKILL.md" + } + ], + "kind": "codex-skill", + "name": "skill:python-skills/python-upgrade-workflow", + "path": "plugins/python-skills/skills/python-upgrade-workflow/SKILL.md" + }, { "dependencies": [], "evidence": [ diff --git a/docs/maintainers/python-skills-plugin-plan.md b/docs/maintainers/python-skills-plugin-plan.md index f78c8c8a..5c6d4583 100644 --- a/docs/maintainers/python-skills-plugin-plan.md +++ b/docs/maintainers/python-skills-plugin-plan.md @@ -237,16 +237,16 @@ The first slice should repair the current child contract and add the core missin - [x] Add `python-skills:python-package-workflow`. - [x] Add `python-skills:python-tooling-style-workflow`. - [x] Update `plugins/python-skills/.codex-plugin/plugin.json` default prompts and long description after the new skills exist. -- [ ] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. -- [ ] Run root Socket metadata validation with `uv run scripts/validate_socket_metadata.py`. +- [x] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. +- [x] Run root Socket metadata validation with `uv run scripts/validate_socket_metadata.py`. ## Second Implementation Slice The second slice should cover repeated project operations that become more valuable after the core skill set lands: -- [ ] Add `python-skills:python-ci-workflow`. -- [ ] Add `python-skills:python-upgrade-workflow`. -- [ ] Decide whether to broaden `uv-pytest-unit-testing` into `python-testing-workflow`. +- [x] Add `python-skills:python-ci-workflow`. +- [x] Add `python-skills:python-upgrade-workflow`. +- [x] Decide whether to broaden `uv-pytest-unit-testing` into `python-testing-workflow`; keep `uv-pytest-unit-testing` for this release so existing prompts and routing remain compatible. - [ ] Decide whether ongoing FastAPI service maintenance needs a dedicated `fastapi-service-workflow`. - [ ] Decide whether ongoing FastMCP server maintenance needs a dedicated `fastmcp-service-workflow`. - [ ] Add install testing with a temporary `CODEX_HOME` if the exported skill surface or plugin metadata changes enough to need plugin-install verification. @@ -295,8 +295,9 @@ The validator repair alone is a maintenance fix. Adding the new skill inventory The expansion is ready when: - [x] The child validator passes without requiring a child `README.md`. -- [ ] The plugin has a documented skill naming convention and expansion plan. +- [x] The plugin has a documented skill naming convention and expansion plan. - [x] The first new skill set covers project choice, implementation, diagnostics, packaging, and tooling/style alignment. -- [ ] The guidance consistently uses `uv` for Python command examples. -- [ ] The guidance uses official documentation as the source of truth for Python packaging, `uv`, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. -- [ ] Root Socket docs, plugin metadata, child validation, and root validation agree on the exported Python skill surface. +- [x] The second new skill set covers CI and upgrade workflows. +- [x] The guidance consistently uses `uv` for Python command examples. +- [x] The guidance uses official documentation as the source of truth for Python packaging, `uv`, pytest, Ruff, mypy, FastAPI, FastMCP, and CI behavior. +- [x] Root Socket docs, plugin metadata, child validation, and root validation agree on the exported Python skill surface. diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json index 99bedb12..5f338c85 100644 --- a/plugins/python-skills/.codex-plugin/plugin.json +++ b/plugins/python-skills/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "python-skills", "version": "6.9.0", - "description": "Bundled Python-focused Codex skills for uv bootstrapping, project implementation, diagnostics, packaging, tooling, FastAPI, FastMCP, and pytest workflows.", + "description": "Bundled Python-focused Codex skills for uv bootstrapping, project implementation, diagnostics, packaging, tooling, CI, upgrades, FastAPI, FastMCP, and pytest workflows.", "author": { "name": "Gale", "email": "mail@galewilliams.com", @@ -21,13 +21,15 @@ "integration", "packaging", "diagnostics", - "tooling" + "tooling", + "ci", + "upgrades" ], "skills": "./skills/", "interface": { "displayName": "Python Skills", - "shortDescription": "Python project, uv, FastAPI, FastMCP, pytest, packaging, and tooling workflows for Codex.", - "longDescription": "Bundle reusable Codex skills for choosing Python project shapes, building uv-managed Python projects, diagnosing Python failures, validating package surfaces, aligning tooling, bootstrapping FastAPI and FastMCP services, integrating FastAPI/FastMCP apps, and setting up pytest workflows.", + "shortDescription": "Python project, uv, FastAPI, FastMCP, pytest, package, tooling, CI, and upgrade workflows for Codex.", + "longDescription": "Bundle reusable Codex skills for choosing Python project shapes, building uv-managed Python projects, diagnosing Python failures, validating package surfaces, aligning tooling, maintaining CI, planning upgrades, bootstrapping FastAPI and FastMCP services, integrating FastAPI/FastMCP apps, and setting up pytest workflows.", "developerName": "gaelic-ghost", "category": "Developer Tools", "capabilities": [ @@ -42,6 +44,8 @@ "Diagnose why this Python uv, import, pytest, Ruff, mypy, FastAPI, FastMCP, or package command failed.", "Validate this Python package surface without publishing it.", "Align this Python repo's uv, Ruff, mypy, pytest, dependency-group, and validation workflow.", + "Align this Python repo's CI with local uv validation commands.", + "Plan this Python dependency, framework, lockfile, or tooling upgrade with staged validation.", "Set up pytest defaults for this uv workspace and show the right package-targeted test commands.", "Add a FastMCP surface to an existing FastAPI project and choose the right combined-app pattern." ], diff --git a/plugins/python-skills/skills/python-ci-workflow/SKILL.md b/plugins/python-skills/skills/python-ci-workflow/SKILL.md new file mode 100644 index 00000000..b3f77d5f --- /dev/null +++ b/plugins/python-skills/skills/python-ci-workflow/SKILL.md @@ -0,0 +1,126 @@ +--- +name: python-ci-workflow +description: Design and maintain Python CI workflows around uv, pytest, Ruff, mypy, package build checks, dependency caching, Python version matrices, and local-command parity. +license: Apache-2.0 +compatibility: Designed for Codex and compatible Agent Skills clients maintaining Python CI for uv-managed projects, packages, services, FastAPI apps, FastMCP servers, and workspaces. +metadata: + owner: gaelic-ghost + repo: python-skills + category: python-ci +allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*) +--- + +# Python CI Workflow + +## Purpose + +Make Python CI prove the same behavior maintainers care about locally. + +The practical job is to choose Python setup, `uv` installation, dependency sync, pytest, Ruff, mypy, package-build checks, path filters, and matrix scope without making CI broader or noisier than the project needs. + +## When To Use + +- Use this skill when adding or changing CI for a Python repository. +- Use this skill when local Python validation and CI disagree. +- Use this skill when adding Python packages, services, FastAPI apps, FastMCP servers, or workspace members to an existing CI workflow. +- Use this skill before package or release workflows depend on CI results. + +## Source Check + +Use official documentation first: + +- [GitHub Actions Python documentation](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python) +- [uv GitHub Actions integration](https://docs.astral.sh/uv/guides/integration/github/) +- [pytest documentation](https://docs.pytest.org/en/stable/) +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [mypy documentation](https://mypy.readthedocs.io/en/stable/) +- [Python packaging user guide](https://packaging.python.org/) + +## CI Planning Workflow + +1. Inspect local validation commands and project metadata: + ```bash + rg --files -g 'pyproject.toml' -g 'uv.lock' -g '.python-version' -g '.github/workflows/*.yml' -g '.github/workflows/*.yaml' + ``` +2. Inspect existing workflow files: + ```bash + rg --files .github/workflows -g '*.yml' -g '*.yaml' + ``` +3. Check Python version sources: + - `requires-python` + - `.python-version` + - workflow `python-version` + - repository docs +4. Decide job scope: + - dependency sync + - tests + - lint + - format check + - type check + - package build +5. Decide matrix scope: + - one Python version for app/service CI unless compatibility is the point + - multiple Python versions for public packages that promise a version range + - one OS unless filesystem, process, path, native dependency, or user-facing CLI behavior requires cross-platform checks +6. Keep local and CI commands aligned. + +## Baseline Command Order + +Prefer a simple shape: + +```bash +uv sync --dev +uv run pytest +uv run ruff check . +uv run mypy . +``` + +Add formatting verification only when the repo enforces Ruff formatting: + +```bash +uv run ruff format --check . +``` + +Add package validation only for package surfaces: + +```bash +uv build +``` + +For workspaces, target package-specific jobs explicitly when the repo does not need a full workspace sweep: + +```bash +uv run --package pytest +uv run --package mypy . +uv build --package +``` + +## GitHub Actions Shape + +Use the repo's existing workflow style first. + +For new GitHub Actions workflows: + +- install `uv` through the official setup action or documented installer path +- use `uv sync --dev` unless the repo documents a narrower sync command +- cache only when it measurably helps and the cache key includes lockfile state +- keep package build or publish steps separate from normal validation +- avoid CI secrets unless a workflow truly needs private package sources or publishing + +## Output Shape + +Return: + +1. `Existing CI`: workflows, Python versions, uv setup, and checks. +2. `Local parity`: local commands CI should mirror. +3. `Change`: workflow, matrix, cache, package build, or docs update. +4. `Commands`: exact local commands and CI job commands. +5. `Residual risk`: checks still manual, secrets needed, or matrix not covered. + +## Guardrails + +- Do not publish packages from CI unless the user explicitly asked for release automation. +- Do not add broad OS or Python matrices without a concrete compatibility reason. +- Do not make CI depend on globally installed Python tools. +- Do not add machine-local paths, private checkout paths, or local package sources to workflows. +- Do not hide failing local validation by making CI narrower than the repo's documented checks. diff --git a/plugins/python-skills/skills/python-ci-workflow/agents/openai.yaml b/plugins/python-skills/skills/python-ci-workflow/agents/openai.yaml new file mode 100644 index 00000000..8156ff1f --- /dev/null +++ b/plugins/python-skills/skills/python-ci-workflow/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Python CI Workflow" + short_description: "Align Python CI around uv, pytest, Ruff, mypy, package builds, and local validation parity." + brand_color: "#2563EB" + default_prompt: "Use $python-ci-workflow to inspect this repository's Python CI, align it with local uv validation commands, choose matrix and cache scope, and avoid publishing unless explicitly requested." + +policy: + allow_implicit_invocation: true diff --git a/plugins/python-skills/skills/python-upgrade-workflow/SKILL.md b/plugins/python-skills/skills/python-upgrade-workflow/SKILL.md new file mode 100644 index 00000000..c169016c --- /dev/null +++ b/plugins/python-skills/skills/python-upgrade-workflow/SKILL.md @@ -0,0 +1,129 @@ +--- +name: python-upgrade-workflow +description: Plan and validate Python version, dependency, uv lockfile, FastAPI, FastMCP, Pydantic, Ruff, mypy, pytest, and package metadata upgrades with staged checks. +license: Apache-2.0 +compatibility: Designed for Codex and compatible Agent Skills clients upgrading Python, uv-managed dependencies, package metadata, frameworks, and maintainer tooling. +metadata: + owner: gaelic-ghost + repo: python-skills + category: python-upgrade +allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*) +--- + +# Python Upgrade Workflow + +## Purpose + +Upgrade Python projects without losing track of compatibility, validation, or package-consumer impact. + +The practical job is to inventory Python requirements, dependency groups, lockfile state, framework versions, tooling strictness, and public package promises; apply one coherent upgrade slice; then run staged validation and document migration notes when users or contributors need them. + +## When To Use + +- Use this skill when changing `requires-python`, `.python-version`, or CI Python versions. +- Use this skill when changing `uv.lock`. +- Use this skill when upgrading runtime dependencies, optional dependencies, or dependency groups. +- Use this skill when upgrading FastAPI, FastMCP, Pydantic, Ruff, mypy, pytest, or other workflow-shaping tools. +- Use this skill when package consumers, service operators, or contributors may need migration notes. + +## Source Check + +Use official documentation first: + +- [uv documentation](https://docs.astral.sh/uv/) +- [Python packaging user guide](https://packaging.python.org/) +- [Python package version specifiers](https://packaging.python.org/specifications/version-specifiers/) +- [FastAPI documentation](https://fastapi.tiangolo.com/) +- [FastMCP documentation](https://gofastmcp.com/getting-started/welcome) +- [Pydantic documentation](https://docs.pydantic.dev/) +- [pytest documentation](https://docs.pytest.org/en/stable/) +- [Ruff documentation](https://docs.astral.sh/ruff/) +- [mypy documentation](https://mypy.readthedocs.io/en/stable/) + +## Upgrade Workflow + +1. Inventory current state: + ```bash + rg -n "requires-python|dependencies|optional-dependencies|dependency-groups|tool.uv|tool.pytest|tool.ruff|tool.mypy|fastapi|fastmcp|pydantic|pytest|ruff|mypy" pyproject.toml uv.lock .github docs README.md + rg --files -g 'pyproject.toml' -g 'uv.lock' -g '.python-version' -g '.github/workflows/*.yml' -g '.github/workflows/*.yaml' + ``` +2. Decide upgrade boundary: + - Python version only + - runtime dependencies only + - maintainer tools only + - framework major or minor upgrade + - package metadata and compatibility range + - lockfile refresh without requirement changes +3. Read release notes or migration docs for version jumps that may change behavior. +4. Apply one coherent upgrade slice. +5. Run staged validation: + ```bash + uv sync --dev + uv run pytest + uv run ruff check . + uv run mypy . + ``` +6. Add package build validation when package surfaces exist: + ```bash + uv build + ``` +7. Update docs, CI, release notes, or migration guidance when contributor setup, package requirements, or runtime behavior changes. + +## Dependency Boundary Notes + +Keep dependency changes in the right place: + +- runtime imports belong in `[project].dependencies` +- optional user-facing features belong in `[project.optional-dependencies]` +- maintainer tools belong in `[dependency-groups]` +- local workspace relationships belong in `[tool.uv.sources]` + +Do not move tools into runtime dependencies to make CI easier. + +## Python Version Notes + +When changing Python version support: + +- update `requires-python` +- update `.python-version` when present +- update CI matrices or setup versions +- check lockfile compatibility +- check package classifiers when the repo ships them +- mention migration impact for contributors or package consumers + +For public packages, do not narrow supported Python versions without treating it as a compatibility decision. + +## Framework Notes + +For FastAPI, FastMCP, and Pydantic upgrades: + +- check startup and lifespan behavior +- check settings and validation behavior +- check generated or mounted MCP surfaces +- run tests that cover app construction and representative endpoints or tools +- update integration guidance when the public app shape changes + +For Ruff, mypy, and pytest upgrades: + +- separate new tool findings from behavior changes +- avoid broad suppressions +- update config only when the new version requires or justifies it + +## Output Shape + +Return: + +1. `Upgrade boundary`: Python, runtime dependencies, tooling, framework, package metadata, or lockfile. +2. `Changed versions`: before and after. +3. `Compatibility impact`: contributors, package consumers, service operators, or none. +4. `Validation`: exact commands run and results. +5. `Docs`: migration notes, CI changes, release notes, or none. +6. `Residual risk`: checks still missing or behavior not covered. + +## Guardrails + +- Do not combine unrelated upgrade families unless the repo already requires one coherent migration. +- Do not refresh lockfiles casually inside unrelated behavior changes. +- Do not narrow Python version support silently. +- Do not suppress new lint or type errors broadly after tool upgrades. +- Do not publish packages or create releases unless the user explicitly asks for that release step. diff --git a/plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml b/plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml new file mode 100644 index 00000000..55a5572e --- /dev/null +++ b/plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml @@ -0,0 +1,8 @@ +interface: + display_name: "Python Upgrade Workflow" + short_description: "Plan and validate Python, dependency, framework, lockfile, and tooling upgrades." + brand_color: "#7C3AED" + default_prompt: "Use $python-upgrade-workflow to inventory Python requirements, dependencies, uv lockfile state, frameworks, tooling versions, compatibility impact, and staged validation before applying an upgrade." + +policy: + allow_implicit_invocation: true From e5ac4cc4a019d444dbc09b6256bb49ad2211bb4a Mon Sep 17 00:00:00 2001 From: Gale W Date: Fri, 15 May 2026 11:55:53 -0400 Subject: [PATCH 4/6] plugin: fix python-skills release metadata --- docs/architecture/architecture.json | 2 +- docs/maintainers/python-skills-plugin-plan.md | 2 +- plugins/python-skills/.codex-plugin/plugin.json | 6 +++--- plugins/python-skills/tests/test_plugin_smoke.py | 3 +++ 4 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/architecture/architecture.json b/docs/architecture/architecture.json index 60faaf5c..28eb889f 100644 --- a/docs/architecture/architecture.json +++ b/docs/architecture/architecture.json @@ -1,5 +1,5 @@ { - "detectedAt": "2026-05-15T15:28:43.389437+00:00", + "detectedAt": "2026-05-15T15:49:48.243930+00:00", "detectionSource": "plugin-repo", "evidence": [ { diff --git a/docs/maintainers/python-skills-plugin-plan.md b/docs/maintainers/python-skills-plugin-plan.md index 5c6d4583..75ccb9b8 100644 --- a/docs/maintainers/python-skills-plugin-plan.md +++ b/docs/maintainers/python-skills-plugin-plan.md @@ -249,7 +249,7 @@ The second slice should cover repeated project operations that become more valua - [x] Decide whether to broaden `uv-pytest-unit-testing` into `python-testing-workflow`; keep `uv-pytest-unit-testing` for this release so existing prompts and routing remain compatible. - [ ] Decide whether ongoing FastAPI service maintenance needs a dedicated `fastapi-service-workflow`. - [ ] Decide whether ongoing FastMCP server maintenance needs a dedicated `fastmcp-service-workflow`. -- [ ] Add install testing with a temporary `CODEX_HOME` if the exported skill surface or plugin metadata changes enough to need plugin-install verification. +- [x] Add install testing with a temporary `CODEX_HOME` if the exported skill surface or plugin metadata changes enough to need plugin-install verification. ## Deferred Scope diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json index 5f338c85..c4f4c7f1 100644 --- a/plugins/python-skills/.codex-plugin/plugin.json +++ b/plugins/python-skills/.codex-plugin/plugin.json @@ -7,8 +7,8 @@ "email": "mail@galewilliams.com", "url": "https://github.com/gaelic-ghost" }, - "homepage": "https://github.com/gaelic-ghost/python-skills", - "repository": "https://github.com/gaelic-ghost/python-skills", + "homepage": "https://github.com/gaelic-ghost/socket/tree/main/plugins/python-skills", + "repository": "https://github.com/gaelic-ghost/socket", "license": "Apache-2.0", "keywords": [ "codex", @@ -36,7 +36,7 @@ "Read", "Write" ], - "websiteURL": "https://github.com/gaelic-ghost/python-skills", + "websiteURL": "https://github.com/gaelic-ghost/socket/tree/main/plugins/python-skills", "defaultPrompt": [ "Bootstrap a new uv FastAPI service with typed settings and a committed .env baseline.", "Choose the right Python project shape before we start implementing.", diff --git a/plugins/python-skills/tests/test_plugin_smoke.py b/plugins/python-skills/tests/test_plugin_smoke.py index 64e2e29c..a51bd6a3 100644 --- a/plugins/python-skills/tests/test_plugin_smoke.py +++ b/plugins/python-skills/tests/test_plugin_smoke.py @@ -33,8 +33,11 @@ def test_plugin_manifest_and_marketplace_contract() -> None: assert manifest["name"] == "python-skills" assert manifest["skills"] == "./skills/" + assert manifest["homepage"] == "https://github.com/gaelic-ghost/socket/tree/main/plugins/python-skills" + assert manifest["repository"] == "https://github.com/gaelic-ghost/socket" assert manifest["interface"]["displayName"] == "Python Skills" assert manifest["interface"]["category"] == "Developer Tools" + assert manifest["interface"]["websiteURL"] == "https://github.com/gaelic-ghost/socket/tree/main/plugins/python-skills" assert ".codex-plugin/plugin.json" in agents_text assert "Root [`skills/`](./skills/) is the authored workflow surface" in agents_text From 9c1c4d177c5e41ff1cca8f6f8272cc007a7b1200 Mon Sep 17 00:00:00 2001 From: Gale W Date: Fri, 15 May 2026 11:57:56 -0400 Subject: [PATCH 5/6] release: prepare socket 6.10.0 --- plugins/agent-plugin-skills/.codex-plugin/plugin.json | 2 +- plugins/agent-plugin-skills/pyproject.toml | 2 +- plugins/agent-plugin-skills/uv.lock | 2 +- plugins/apple-dev-skills/.codex-plugin/plugin.json | 2 +- plugins/apple-dev-skills/pyproject.toml | 2 +- plugins/apple-dev-skills/uv.lock | 2 +- plugins/cardhop-app/.codex-plugin/plugin.json | 2 +- plugins/cardhop-app/mcp/pyproject.toml | 2 +- plugins/cardhop-app/mcp/uv.lock | 2 +- plugins/dotnet-skills/.codex-plugin/plugin.json | 2 +- plugins/productivity-skills/.codex-plugin/plugin.json | 2 +- plugins/productivity-skills/pyproject.toml | 2 +- plugins/productivity-skills/uv.lock | 2 +- plugins/python-skills/.codex-plugin/plugin.json | 2 +- plugins/python-skills/pyproject.toml | 2 +- plugins/python-skills/uv.lock | 2 +- plugins/rust-skills/.codex-plugin/plugin.json | 2 +- plugins/spotify/.codex-plugin/plugin.json | 2 +- plugins/swiftasb-skills/.codex-plugin/plugin.json | 2 +- plugins/things-app/.codex-plugin/plugin.json | 2 +- plugins/things-app/mcp/pyproject.toml | 2 +- plugins/things-app/mcp/uv.lock | 2 +- plugins/things-app/pyproject.toml | 2 +- plugins/things-app/uv.lock | 2 +- plugins/web-dev-skills/.codex-plugin/plugin.json | 2 +- pyproject.toml | 2 +- uv.lock | 2 +- 27 files changed, 27 insertions(+), 27 deletions(-) diff --git a/plugins/agent-plugin-skills/.codex-plugin/plugin.json b/plugins/agent-plugin-skills/.codex-plugin/plugin.json index 7d8e5048..289e5254 100644 --- a/plugins/agent-plugin-skills/.codex-plugin/plugin.json +++ b/plugins/agent-plugin-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-plugin-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Installable maintainer skills for skills-export repositories.", "author": { "name": "Gale", diff --git a/plugins/agent-plugin-skills/pyproject.toml b/plugins/agent-plugin-skills/pyproject.toml index a76f7715..90fedd2f 100644 --- a/plugins/agent-plugin-skills/pyproject.toml +++ b/plugins/agent-plugin-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agent-plugin-skills-maintenance" -version = "6.9.0" +version = "6.10.0" description = "Maintainer-only Python tooling baseline for agent-plugin-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/agent-plugin-skills/uv.lock b/plugins/agent-plugin-skills/uv.lock index 01878104..a59fcc3d 100644 --- a/plugins/agent-plugin-skills/uv.lock +++ b/plugins/agent-plugin-skills/uv.lock @@ -4,7 +4,7 @@ requires-python = ">=3.11" [[package]] name = "agent-plugin-skills-maintenance" -version = "6.9.0" +version = "6.10.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/apple-dev-skills/.codex-plugin/plugin.json b/plugins/apple-dev-skills/.codex-plugin/plugin.json index 7d83b4e2..cb9cd28a 100644 --- a/plugins/apple-dev-skills/.codex-plugin/plugin.json +++ b/plugins/apple-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "apple-dev-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Apple development workflows for Codex, including SwiftUI architecture, Safari extensions, and DocC authoring guidance.", "author": { "name": "Gale", diff --git a/plugins/apple-dev-skills/pyproject.toml b/plugins/apple-dev-skills/pyproject.toml index a59bbdbd..938cb339 100644 --- a/plugins/apple-dev-skills/pyproject.toml +++ b/plugins/apple-dev-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "apple-dev-skills-maintainer" -version = "6.9.0" +version = "6.10.0" description = "Maintainer tooling for the apple-dev-skills repository" requires-python = ">=3.9" dependencies = [] diff --git a/plugins/apple-dev-skills/uv.lock b/plugins/apple-dev-skills/uv.lock index 0850d01d..3327da9c 100644 --- a/plugins/apple-dev-skills/uv.lock +++ b/plugins/apple-dev-skills/uv.lock @@ -8,7 +8,7 @@ resolution-markers = [ [[package]] name = "apple-dev-skills-maintainer" -version = "6.9.0" +version = "6.10.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/cardhop-app/.codex-plugin/plugin.json b/plugins/cardhop-app/.codex-plugin/plugin.json index 45be5918..72444aec 100644 --- a/plugins/cardhop-app/.codex-plugin/plugin.json +++ b/plugins/cardhop-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cardhop-app", - "version": "6.9.0", + "version": "6.10.0", "description": "Cardhop.app workflow guidance plus a bundled local MCP server for contact capture and updates on macOS.", "author": { "name": "Gale", diff --git a/plugins/cardhop-app/mcp/pyproject.toml b/plugins/cardhop-app/mcp/pyproject.toml index ba66644e..c221cf58 100644 --- a/plugins/cardhop-app/mcp/pyproject.toml +++ b/plugins/cardhop-app/mcp/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "cardhop-app-mcp" -version = "6.9.0" +version = "6.10.0" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/cardhop-app/mcp/uv.lock b/plugins/cardhop-app/mcp/uv.lock index e4f28181..2d5741a1 100644 --- a/plugins/cardhop-app/mcp/uv.lock +++ b/plugins/cardhop-app/mcp/uv.lock @@ -93,7 +93,7 @@ wheels = [ [[package]] name = "cardhop-app-mcp" -version = "6.9.0" +version = "6.10.0" source = { virtual = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/dotnet-skills/.codex-plugin/plugin.json b/plugins/dotnet-skills/.codex-plugin/plugin.json index aa23b1ca..39509eea 100644 --- a/plugins/dotnet-skills/.codex-plugin/plugin.json +++ b/plugins/dotnet-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dotnet-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Codex skills for choosing, bootstrapping, building, testing, packaging, diagnosing, and maintaining .NET projects with F# and C# as equal first-party languages.", "author": { "name": "Gale", diff --git a/plugins/productivity-skills/.codex-plugin/plugin.json b/plugins/productivity-skills/.codex-plugin/plugin.json index 6ae6925b..60c0097f 100644 --- a/plugins/productivity-skills/.codex-plugin/plugin.json +++ b/plugins/productivity-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "productivity-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Broadly useful productivity workflows for Codex.", "author": { "name": "Gale", diff --git a/plugins/productivity-skills/pyproject.toml b/plugins/productivity-skills/pyproject.toml index b9f1fe19..cc778344 100644 --- a/plugins/productivity-skills/pyproject.toml +++ b/plugins/productivity-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "productivity-skills-maintenance" -version = "6.9.0" +version = "6.10.0" description = "Maintainer-only Python tooling baseline for productivity-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/productivity-skills/uv.lock b/plugins/productivity-skills/uv.lock index 43f13830..663ceef7 100644 --- a/plugins/productivity-skills/uv.lock +++ b/plugins/productivity-skills/uv.lock @@ -40,7 +40,7 @@ wheels = [ [[package]] name = "productivity-skills-maintenance" -version = "6.9.0" +version = "6.10.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json index c4f4c7f1..ac5e70b0 100644 --- a/plugins/python-skills/.codex-plugin/plugin.json +++ b/plugins/python-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "python-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Bundled Python-focused Codex skills for uv bootstrapping, project implementation, diagnostics, packaging, tooling, CI, upgrades, FastAPI, FastMCP, and pytest workflows.", "author": { "name": "Gale", diff --git a/plugins/python-skills/pyproject.toml b/plugins/python-skills/pyproject.toml index c810ea2e..1f4e52d9 100644 --- a/plugins/python-skills/pyproject.toml +++ b/plugins/python-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "python-skills-maintainer" -version = "6.9.0" +version = "6.10.0" description = "Maintainer tooling for the python-skills repository" requires-python = ">=3.11" dependencies = [] diff --git a/plugins/python-skills/uv.lock b/plugins/python-skills/uv.lock index d1e5ae74..fc934fe2 100644 --- a/plugins/python-skills/uv.lock +++ b/plugins/python-skills/uv.lock @@ -206,7 +206,7 @@ wheels = [ [[package]] name = "python-skills-maintainer" -version = "6.9.0" +version = "6.10.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/rust-skills/.codex-plugin/plugin.json b/plugins/rust-skills/.codex-plugin/plugin.json index f04c0f0e..5a6580d8 100644 --- a/plugins/rust-skills/.codex-plugin/plugin.json +++ b/plugins/rust-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rust-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Standalone plugin repository for future Rust-focused Codex skills.", "author": { "name": "Gale", diff --git a/plugins/spotify/.codex-plugin/plugin.json b/plugins/spotify/.codex-plugin/plugin.json index a4894525..0eae2bcc 100644 --- a/plugins/spotify/.codex-plugin/plugin.json +++ b/plugins/spotify/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "spotify", - "version": "6.9.0", + "version": "6.10.0", "description": "Placeholder plugin repository for future Spotify-focused Codex workflows.", "author": { "name": "Gale", diff --git a/plugins/swiftasb-skills/.codex-plugin/plugin.json b/plugins/swiftasb-skills/.codex-plugin/plugin.json index 916d4979..fef2c49f 100644 --- a/plugins/swiftasb-skills/.codex-plugin/plugin.json +++ b/plugins/swiftasb-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "swiftasb-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Codex skills for explaining SwiftASB and building SwiftUI, AppKit, and Swift package integrations on top of it.", "author": { "name": "Gale", diff --git a/plugins/things-app/.codex-plugin/plugin.json b/plugins/things-app/.codex-plugin/plugin.json index 9ebef96a..969008ea 100644 --- a/plugins/things-app/.codex-plugin/plugin.json +++ b/plugins/things-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "things-app", - "version": "6.9.0", + "version": "6.10.0", "description": "Things.app skills and a bundled local MCP server for reminders, planning digests, and structured task workflows.", "author": { "name": "Gale", diff --git a/plugins/things-app/mcp/pyproject.toml b/plugins/things-app/mcp/pyproject.toml index b1a2c55a..b3897a22 100644 --- a/plugins/things-app/mcp/pyproject.toml +++ b/plugins/things-app/mcp/pyproject.toml @@ -7,7 +7,7 @@ packages = ["app"] [project] name = "things-mcp" -version = "6.9.0" +version = "6.10.0" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/things-app/mcp/uv.lock b/plugins/things-app/mcp/uv.lock index 71b4556b..cbabe97c 100644 --- a/plugins/things-app/mcp/uv.lock +++ b/plugins/things-app/mcp/uv.lock @@ -1118,7 +1118,7 @@ wheels = [ [[package]] name = "things-mcp" -version = "6.9.0" +version = "6.10.0" source = { editable = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/things-app/pyproject.toml b/plugins/things-app/pyproject.toml index 6859425a..7655844f 100644 --- a/plugins/things-app/pyproject.toml +++ b/plugins/things-app/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "things-app-maintenance" -version = "6.9.0" +version = "6.10.0" description = "Maintainer-only Python tooling baseline for things-app skills and plugin packaging." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/things-app/uv.lock b/plugins/things-app/uv.lock index 34a591ef..3419652c 100644 --- a/plugins/things-app/uv.lock +++ b/plugins/things-app/uv.lock @@ -120,7 +120,7 @@ wheels = [ [[package]] name = "things-app-maintenance" -version = "6.9.0" +version = "6.10.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/web-dev-skills/.codex-plugin/plugin.json b/plugins/web-dev-skills/.codex-plugin/plugin.json index c2d75a84..dd24a127 100644 --- a/plugins/web-dev-skills/.codex-plugin/plugin.json +++ b/plugins/web-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "web-dev-skills", - "version": "6.9.0", + "version": "6.10.0", "description": "Standalone plugin repository for future web-focused Codex skills.", "author": { "name": "Gale", diff --git a/pyproject.toml b/pyproject.toml index f5f97412..e6921840 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "socket-maintenance" -version = "6.9.0" +version = "6.10.0" description = "Root uv tooling baseline for the socket superproject." requires-python = ">=3.11" dependencies = [] diff --git a/uv.lock b/uv.lock index 4fde04e5..ec027388 100644 --- a/uv.lock +++ b/uv.lock @@ -286,7 +286,7 @@ wheels = [ [[package]] name = "socket-maintenance" -version = "6.9.0" +version = "6.10.0" source = { virtual = "." } [package.dev-dependencies] From b00d35b644536b7ea8e1abf20624f4fd5b7a25f6 Mon Sep 17 00:00:00 2001 From: Gale W Date: Fri, 15 May 2026 13:35:12 -0400 Subject: [PATCH 6/6] plugin: address python-skills review comments --- README.md | 2 +- docs/architecture/architecture.json | 2 +- .../references/architecture-json.md | 2 +- .../scripts/maintain_project_architecture.py | 2 +- .../tests/test_maintain_project_architecture.py | 3 +++ .../skills/choose-python-project-shape/agents/openai.yaml | 2 +- plugins/python-skills/skills/python-upgrade-workflow/SKILL.md | 2 +- .../skills/python-upgrade-workflow/agents/openai.yaml | 2 +- 8 files changed, 10 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c01d51cb..9f5cd0c0 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ Current Socket catalog shape: - `cardhop-app`: mixed skill plus bundled MCP server for Cardhop.app contact workflows - `dotnet-skills`: .NET, F#, and C# project-shape, bootstrap, implementation, test, package, diagnostics, ASP.NET Core, interop, CI, upgrade, and tooling guidance - `productivity-skills`: general-purpose maintainer and documentation workflow baseline -- `python-skills`: Python, `uv`, project implementation, diagnostics, packaging, tooling, CI, upgrades, FastAPI, FastMCP, and pytest workflow plugin +- `python-skills`: Python runtime and tooling workflows for Python-based projects; see the [Python skills expansion plan](./docs/maintainers/python-skills-plugin-plan.md) for maintainer details - `speak-swiftly`: Git-backed Speak Swiftly plugin from the standalone SpeakSwiftlyServer repository - `swiftasb-skills`: SwiftASB companion guidance - `things-app`: mixed skill plus bundled MCP server for Things.app workflows diff --git a/docs/architecture/architecture.json b/docs/architecture/architecture.json index 28eb889f..88db3a63 100644 --- a/docs/architecture/architecture.json +++ b/docs/architecture/architecture.json @@ -498,7 +498,7 @@ "targets": [] } ], - "projectRoot": "/Users/galew/Workspace/gaelic-ghost/socket-wt-python-skills-gap-analysis", + "projectRoot": ".", "relationships": [ { "evidence": [ diff --git a/plugins/productivity-skills/skills/maintain-project-architecture/references/architecture-json.md b/plugins/productivity-skills/skills/maintain-project-architecture/references/architecture-json.md index 4ab77456..9b4d9058 100644 --- a/plugins/productivity-skills/skills/maintain-project-architecture/references/architecture-json.md +++ b/plugins/productivity-skills/skills/maintain-project-architecture/references/architecture-json.md @@ -8,7 +8,7 @@ { "schemaVersion": 1, "generatedBy": "maintain-project-architecture", - "projectRoot": "/path/to/repo", + "projectRoot": ".", "detectedAt": "2026-05-03T00:00:00Z", "products": [], "targets": [], diff --git a/plugins/productivity-skills/skills/maintain-project-architecture/scripts/maintain_project_architecture.py b/plugins/productivity-skills/skills/maintain-project-architecture/scripts/maintain_project_architecture.py index 9eacd15c..27645bb9 100644 --- a/plugins/productivity-skills/skills/maintain-project-architecture/scripts/maintain_project_architecture.py +++ b/plugins/productivity-skills/skills/maintain-project-architecture/scripts/maintain_project_architecture.py @@ -433,7 +433,7 @@ def detect_model(project_root: Path) -> dict[str, Any]: return { "schemaVersion": 1, "generatedBy": "maintain-project-architecture", - "projectRoot": str(project_root), + "projectRoot": ".", "detectedAt": datetime.now(timezone.utc).isoformat(), "detectionSource": source, "products": [item for item in products if item.get("name")], diff --git a/plugins/productivity-skills/skills/maintain-project-architecture/tests/test_maintain_project_architecture.py b/plugins/productivity-skills/skills/maintain-project-architecture/tests/test_maintain_project_architecture.py index d886d1ef..505c61c4 100644 --- a/plugins/productivity-skills/skills/maintain-project-architecture/tests/test_maintain_project_architecture.py +++ b/plugins/productivity-skills/skills/maintain-project-architecture/tests/test_maintain_project_architecture.py @@ -2,6 +2,7 @@ import argparse import importlib.util +import json import sys from pathlib import Path @@ -98,6 +99,8 @@ def test_apply_creates_architecture_files_and_detects_products(tmp_path: Path) - assert (architecture_dir / "ARCHITECTURE.md").is_file() assert (architecture_dir / "SLICES.md").is_file() assert (architecture_dir / "architecture.json").is_file() + model = json.loads((architecture_dir / "architecture.json").read_text(encoding="utf-8")) + assert model["projectRoot"] == "." architecture = (architecture_dir / "ARCHITECTURE.md").read_text(encoding="utf-8") assert "## Product Map" in architecture assert "`DemoCore`" in architecture diff --git a/plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml b/plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml index 61beda80..023920f4 100644 --- a/plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml +++ b/plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml @@ -1,6 +1,6 @@ interface: display_name: "Choose Python Project Shape" - short_description: "Choose Python package, service, MCP, workspace, test, tooling, package, CI, or upgrade shape." + short_description: "Choose Python package, service, MCP, workspace, test, tooling, CI, or upgrade shape." brand_color: "#2563EB" default_prompt: "Use $choose-python-project-shape to inspect this repository, choose the smallest correct Python project shape, recommend the next Python skill, and return exact uv validation commands before implementation starts." diff --git a/plugins/python-skills/skills/python-upgrade-workflow/SKILL.md b/plugins/python-skills/skills/python-upgrade-workflow/SKILL.md index c169016c..9c900544 100644 --- a/plugins/python-skills/skills/python-upgrade-workflow/SKILL.md +++ b/plugins/python-skills/skills/python-upgrade-workflow/SKILL.md @@ -44,7 +44,7 @@ Use official documentation first: 1. Inventory current state: ```bash - rg -n "requires-python|dependencies|optional-dependencies|dependency-groups|tool.uv|tool.pytest|tool.ruff|tool.mypy|fastapi|fastmcp|pydantic|pytest|ruff|mypy" pyproject.toml uv.lock .github docs README.md + rg -n "requires-python|dependencies|optional-dependencies|dependency-groups|tool.uv|tool.pytest|tool.ruff|tool.mypy|fastapi|fastmcp|pydantic|pytest|ruff|mypy" rg --files -g 'pyproject.toml' -g 'uv.lock' -g '.python-version' -g '.github/workflows/*.yml' -g '.github/workflows/*.yaml' ``` 2. Decide upgrade boundary: diff --git a/plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml b/plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml index 55a5572e..d4a77387 100644 --- a/plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml +++ b/plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml @@ -2,7 +2,7 @@ interface: display_name: "Python Upgrade Workflow" short_description: "Plan and validate Python, dependency, framework, lockfile, and tooling upgrades." brand_color: "#7C3AED" - default_prompt: "Use $python-upgrade-workflow to inventory Python requirements, dependencies, uv lockfile state, frameworks, tooling versions, compatibility impact, and staged validation before applying an upgrade." + default_prompt: "Use $python-upgrade-workflow to inventory Python requirements, dependencies, uv lockfile state, frameworks, tooling versions, compatibility impact, and staged validation before applying an upgrade; do not publish or create releases unless explicitly requested." policy: allow_implicit_invocation: true