Python: [BREAKING] update to v1.0.0 (#5062)

* updates to final deprecated pieces and versions

* fix mypy

* fix readme links

python/.github/skills/python-package-management/SKILL.md

@@ -97,13 +97,20 @@ def __getattr__(name: str) -> Any:
 
 **Important:** Do not create a new package unless approved by the core team.
 
-### Initial Release (Preview)
+Every new package starts as `alpha`.
+
+### Alpha package checklist
 
 1. Create directory under `packages/` (e.g., `packages/my-connector/`)
 2. Add the package to `tool.uv.sources` in root `pyproject.toml`
-3. Include samples inside the package (e.g., `packages/my-connector/samples/`)
-4. Do **NOT** add to `[all]` extra in `packages/core/pyproject.toml`
-5. Do **NOT** create lazy loading in core yet
+3. Set the package version to the alpha pattern: `1.0.0a<date>`
+4. Set the package classifier to `Development Status :: 3 - Alpha`
+5. Include samples inside the package (e.g., `packages/my-connector/samples/`)
+6. Do **NOT** add to `[all]` extra in `packages/core/pyproject.toml`
+7. Do **NOT** create lazy loading in core yet
+8. Add the package to `python/PACKAGE_STATUS.md` and keep that file updated when packages are added,
+   removed, renamed, or promoted. If the package exposes individually staged APIs, keep the feature list
+   there current too.
 
 Recommended dependency workflow during connector implementation:
 
@@ -116,17 +123,83 @@ Recommended dependency workflow during connector implementation:
    `uv run poe add-dependency-and-validate-bounds --package core --dependency "<dependency-spec>"`
    If compatibility checks are not in place yet, add the dependency first, then implement tests before running bound validation.
 
-### Promotion to Stable
+### Promotion path
 
-1. Move samples to root `samples/` folder
-2. Add to `[all]` extra in `packages/core/pyproject.toml`
-3. Create provider folder in `agent_framework/` with lazy loading `__init__.py`
+Promotion work is not isolated to the package being promoted. If a promotion changes dependency
+metadata for downstream packages, also update the dependent packages' own versions so they publish
+new metadata alongside the promoted dependency bounds.
+Apply the internal package dependency update rules from the versioning section below during
+promotions as well as standalone version update work.
+
+#### Alpha -> Beta
+
+Move a package to `beta` when it is stable enough to be part of the main install surface.
+
+1. Update the package version to the beta pattern: `1.0.0b<date>`
+2. Update the classifier to `Development Status :: 4 - Beta`
+3. Add the package to `[all]` in `packages/core/pyproject.toml`
+4. Move samples to the root `samples/` tree and remove package-local samples
+5. Create or update the relevant lazy-loading namespace in core when the package belongs under one
+6. Update `python/PACKAGE_STATUS.md`
+
+After `alpha`, there should be no samples left inside a package folder.
+
+#### Beta -> RC
+
+Move a package to `rc` when its API is close to the final released shape.
+
+1. Update the package version to the release-candidate pattern: `1.0.0rc<number>`
+2. Keep the classifier at `Development Status :: 4 - Beta` because PyPI does not have a separate
+   release-candidate classifier
+3. Keep the package in `core[all]`
+4. Keep samples only in the root `samples/` tree
+5. Update `python/PACKAGE_STATUS.md` to show the package as `rc`
+
+#### RC -> Released
+
+Move a package to `released` when it no longer carries a prerelease qualifier.
+
+1. Update the package version to the stable pattern: `1.0.0`
+2. Update the classifier to `Development Status :: 5 - Production/Stable`
+3. Keep the package in `core[all]`
+4. Keep samples only in the root `samples/` tree
+5. Update `python/PACKAGE_STATUS.md` to show the package as `released`
+6. Update all `README.md` files that install that package with
+   `pip install agent-framework-... --pre` so they use `pip install agent-framework-...` without
+   the `--pre` suffix
 
 ## Versioning
 
+### Internal package dependency updates
+
+- If package A depends on package B within this repository, only update package A's dependency
+  declaration when the work on package B actually affects package A.
+- If package A does not need anything from the package B change, leave package A's dependency
+  declaration unchanged.
+- If package A does need something from the package B change, update package A's dependency
+  declaration to the version or versioning scheme that matches what package A now requires.
+- If package B is promoted to a different lifecycle stage, update package A's dependency
+  declaration to the new versioning scheme for package B even when the only change is the stage
+  transition itself.
+- Use this guidance both for ordinary version updates and for package promotion work.
+
 - All non-core packages declare a lower bound on `agent-framework-core`
 - When core version bumps with breaking changes, update the lower bound in all packages
 - Non-core packages version independently; only raise core bound when using new core APIs
+- If promoting a package changes a dependent package's published dependency metadata, bump the
+  dependent package's own version in the correct lifecycle pattern for its current stage
+- Lifecycle version patterns:
+  - `alpha`: `1.0.0a<date>`
+  - `beta`: `1.0.0b<date>`
+  - `rc`: `1.0.0rc<number>`
+  - `released`: `1.0.0`
+- Keep the `Development Status` classifier in `pyproject.toml` aligned with the lifecycle stage:
+  - `alpha` -> `Development Status :: 3 - Alpha`
+  - `beta` -> `Development Status :: 4 - Beta`
+  - `rc` -> `Development Status :: 4 - Beta`
+  - `released` -> `Development Status :: 5 - Production/Stable`
+- See the PyPI classifier list for the available classifier values:
+  `https://pypi.org/classifiers/`
 
 ## Installation Options
 
@@ -144,6 +217,10 @@ When changing a package, check if its `AGENTS.md` needs updates:
 - Changing the package's purpose or architecture
 - Modifying import paths or usage patterns
 
+Keep `python/PACKAGE_STATUS.md` updated when:
+- A package is added, removed, renamed, or promoted between lifecycle stages
+- A package starts or stops exposing individually staged experimental or release-candidate APIs
+
 When a package adds, removes, or renames environment variables, update the related documentation in the same
 change:
 - The package's `README.md` for package-level configuration/env var guidance