workforge 2.4.1__tar.gz → 2.5.0__tar.gz

{workforge-2.4.1 → workforge-2.5.0}/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [2.5.0] - 2026-08-25
+
+### 🚀 Features
+
+- *(workspace)* Add contributor instructions
+
+### 📚 Documentation
+
+- Clarify WorkForge installation modes
 ## [2.4.1] - 2026-08-21
 
 ### 💼 Other
@@ -13,6 +22,7 @@
 
 - *(github pages)* Create theme configuration file
 - Updates documentation
+- Release 2.4.1
 ## [2.4.0] - 2026-08-21
 
 ### 🚀 Features

{workforge-2.4.1 → workforge-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workforge
-Version: 2.4.1
+Version: 2.5.0
 Summary: Turn work inputs into provider-neutral requirements and planning items.
 Project-URL: Homepage, https://github.com/Nanielito/workforge
 Project-URL: Repository, https://github.com/Nanielito/workforge.git
@@ -99,18 +99,27 @@ GitHub Actions runs on pull requests and pushes to `main`.
 
 ## Quick Start
 
-Install WorkForge as an isolated command-line tool:
+`uvx` is included with `uv`. If it is not available yet, install `uv` using the
+[official installation guide](https://docs.astral.sh/uv/getting-started/installation/),
+which covers macOS, Linux, Windows, and common package managers.
+
+Run WorkForge on demand without installing a permanent command:
 
 ```bash
-uv tool install workforge
+uvx workforge --help
 ```
 
-Contributors should continue to use `pip install -e ".[dev]"`.
+Prefix each WorkForge command with `uvx`; the examples below omit that prefix
+for readability. Alternatively, install it persistently with
+`uv tool install workforge`. See the
+[distribution guide](https://github.com/Nanielito/workforge/blob/main/docs/distribution.md#choose-how-to-run-workforge)
+for temporary, persistent, and version-pinned usage. Contributors should
+continue to use `pip install -e ".[dev]"`.
 
 Create a project-local workspace:
 
 ```bash
-workforge init .workforge --name linkealo --provider trello --namespace linkealo/shopify
+workforge init .workforge --name my-project --provider trello --namespace my-project/shopify
 ```
 
 Then add the printed entries to the host project's `.gitignore`:
@@ -255,10 +264,14 @@ workforge providers test --workspace workspaces/trello-example --provider trello
 <workspace>/
   workforge.yaml
   .env.example
+  README.md
   inbox/
   output/
 ```
 
+`workforge init` creates the workspace README with a concise contributor
+workflow for configuring access, previewing requirements, and tracking work.
+
 Workspace `.env` files are intentionally local-only. Commit `.env.example`, not
 `.env`.
 
@@ -376,7 +389,7 @@ workspaces/<name>/
       status.json
       agent-context.md
       items/
-        fix-ui-operativa-post-instalacion.md
+        fix-ui-post-install.md
 ```
 
 `preview.json` contains the provider-neutral requirements parsed from the input.

{workforge-2.4.1 → workforge-2.5.0}/README.md

@@ -67,18 +67,27 @@ GitHub Actions runs on pull requests and pushes to `main`.
 
 ## Quick Start
 
-Install WorkForge as an isolated command-line tool:
+`uvx` is included with `uv`. If it is not available yet, install `uv` using the
+[official installation guide](https://docs.astral.sh/uv/getting-started/installation/),
+which covers macOS, Linux, Windows, and common package managers.
+
+Run WorkForge on demand without installing a permanent command:
 
 ```bash
-uv tool install workforge
+uvx workforge --help
 ```
 
-Contributors should continue to use `pip install -e ".[dev]"`.
+Prefix each WorkForge command with `uvx`; the examples below omit that prefix
+for readability. Alternatively, install it persistently with
+`uv tool install workforge`. See the
+[distribution guide](https://github.com/Nanielito/workforge/blob/main/docs/distribution.md#choose-how-to-run-workforge)
+for temporary, persistent, and version-pinned usage. Contributors should
+continue to use `pip install -e ".[dev]"`.
 
 Create a project-local workspace:
 
 ```bash
-workforge init .workforge --name linkealo --provider trello --namespace linkealo/shopify
+workforge init .workforge --name my-project --provider trello --namespace my-project/shopify
 ```
 
 Then add the printed entries to the host project's `.gitignore`:
@@ -223,10 +232,14 @@ workforge providers test --workspace workspaces/trello-example --provider trello
 <workspace>/
   workforge.yaml
   .env.example
+  README.md
   inbox/
   output/
 ```
 
+`workforge init` creates the workspace README with a concise contributor
+workflow for configuring access, previewing requirements, and tracking work.
+
 Workspace `.env` files are intentionally local-only. Commit `.env.example`, not
 `.env`.
 
@@ -344,7 +357,7 @@ workspaces/<name>/
       status.json
       agent-context.md
       items/
-        fix-ui-operativa-post-instalacion.md
+        fix-ui-post-install.md
 ```
 
 `preview.json` contains the provider-neutral requirements parsed from the input.

{workforge-2.4.1 → workforge-2.5.0}/docs/distribution.md

@@ -1,9 +1,8 @@
 # Distribution and Release Guide
 
-WorkForge is a public Python CLI. GitHub remains the source repository and
-release record; PyPI will be the package distribution channel. This gives users
-an isolated `workforge` command without requiring a repository clone or a
-development environment.
+WorkForge is a public Python CLI distributed through PyPI. GitHub remains the
+source repository and release record. Users can run WorkForge in an isolated
+environment without cloning the repository or creating a development setup.
 
 ## Current state
 
@@ -12,23 +11,54 @@ changelog, creates a Git tag, and uploads the wheel and source distribution to
 both a GitHub Release and PyPI. The PyPI job uses Trusted Publishing and a
 separate GitHub environment so it never receives the repository write token.
 
-PyPI installation commands will work after the one-time publisher setup is
-completed and the first release using the publish job succeeds.
+## Choose how to run WorkForge
 
-## User installation
+`uvx` ships with `uv`; users who do not have it can follow the
+[official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
-The recommended installation uses `uv`, which puts the CLI and its dependencies
-in an isolated environment:
+### On demand in a project
+
+Use `uvx` when WorkForge supports planning for a project but should not become a
+permanent command or project dependency:
+
+```bash
+cd my-project
+uvx workforge init .workforge \
+  --name my-project \
+  --provider github \
+  --namespace organization/repository
+uvx workforge preview .workforge/inbox/requirements.md --workspace .workforge
+```
+
+Prefix every command with `uvx`. The WorkForge runtime remains isolated and uv
+may cache it for faster later executions; the project-local `.workforge`
+workspace persists normally. The same approach works with Trello, GitHub
+Projects, and Jira.
+
+To reproduce planning behavior with a known release, pin it in each invocation:
+
+```bash
+uvx workforge@X.Y.Z preview .workforge/inbox/requirements.md --workspace .workforge
+```
+
+There is nothing to uninstall after `uvx`. `uv cache clean` removes uv's shared
+cache, not only WorkForge, and is normally unnecessary.
+
+### Persistent command
+
+Install WorkForge persistently when it is used across many projects or by
+scripts that expect a `workforge` command on `PATH`:
 
 ```bash
 uv tool install workforge
 workforge --help
 ```
 
-Users can run WorkForge without a permanent installation:
+Upgrade or remove this installation with:
 
 ```bash
-uvx workforge --help
+uv tool upgrade workforge
+uv tool uninstall workforge
 ```
 
 `pipx` provides an equivalent isolated installation:
@@ -40,17 +70,10 @@ pipx install workforge
 Plain `pip install workforge` is supported but is not the recommended default
 because it can mix WorkForge dependencies with another Python environment.
 
-Install or keep a specific version when reproducibility matters:
-
-```bash
-uv tool install workforge==2.4.1
-```
-
-Upgrade or remove the CLI with:
+Pin a persistent installation when reproducibility matters:
 
 ```bash
-uv tool upgrade workforge
-uv tool uninstall workforge
+uv tool install workforge==X.Y.Z
 ```
 
 ## First use
@@ -58,12 +81,15 @@ uv tool uninstall workforge
 Create a workspace inside the project that WorkForge will manage:
 
 ```bash
-workforge init .workforge \
+uvx workforge init .workforge \
   --name my-project \
   --provider github \
   --namespace organization/repository
 ```
 
+The generated `.workforge/README.md` explains how to create provider items from
+a Markdown requirement or discover and continue existing items using `uvx`.
+
 Keep credentials and generated output out of version control:
 
 ```gitignore
@@ -75,19 +101,19 @@ Copy `.workforge/.env.example` to `.workforge/.env`, add the selected provider's
 credentials, and validate them before performing writes:
 
 ```bash
-workforge providers test --workspace .workforge --provider github
+uvx workforge providers test --workspace .workforge --provider github
 ```
 
 Place Markdown requirements in `.workforge/inbox/`. Preview them first:
 
 ```bash
-workforge preview .workforge/inbox/requirements.md --workspace .workforge
+uvx workforge preview .workforge/inbox/requirements.md --workspace .workforge
 ```
 
 Create external planning items only after reviewing the preview:
 
 ```bash
-workforge create .workforge/inbox/requirements.md \
+uvx workforge create .workforge/inbox/requirements.md \
   --workspace .workforge \
   --provider github \
   --execute \

{workforge-2.4.1 → workforge-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workforge"
-version = "2.4.1"
+version = "2.5.0"
 description = "Turn work inputs into provider-neutral requirements and planning items."
 readme = "README.md"
 requires-python = ">=3.11"

{workforge-2.4.1 → workforge-2.5.0}/src/workforge/cli.py

@@ -631,6 +631,7 @@ def _init_workspace(
     files = {
         workspace_path / "workforge.yaml": _workspace_config_template(workspace_name, provider, default_namespace),
         workspace_path / ".env.example": _env_example_template(provider),
+        workspace_path / "README.md": _workspace_readme_template(),
         workspace_path / "output" / ".gitkeep": "",
     }
 
@@ -699,6 +700,54 @@ def _env_example_template(provider: str) -> str:
     return ""
 
 
+def _workspace_readme_template() -> str:
+    return """# WorkForge workspace
+
+This directory contains the planning workspace for this repository. Requirements
+live in `inbox/`; generated provider state and agent context live in `output/`.
+
+## Contributor workflow
+
+1. Copy `.env.example` to `.env` and add your provider credentials.
+2. Validate access with `uvx workforge providers test --workspace .workforge`.
+
+Run WorkForge through `uvx workforge` so contributors use an isolated CLI
+without installing it into the project.
+
+### Start from a requirement
+
+Create `inbox/<requirement>.md` with one `## Title` section per planning item,
+optional metadata such as `Labels: docs`, a description, and `- Task` lines.
+Then preview it before any external write:
+
+`uvx workforge preview .workforge/inbox/<requirement>.md --workspace .workforge`
+
+After approval, create and save the provider items:
+
+`uvx workforge create .workforge/inbox/<requirement>.md --workspace .workforge --execute --save`
+
+### Continue existing items
+
+Discover existing provider items into the default `discovered` output:
+
+`uvx workforge discover --workspace .workforge --save`
+
+Claim the selected item and move it into progress:
+
+`uvx workforge claim-item discovered --workspace .workforge --item <id> --assignee @me`
+
+`uvx workforge move-item discovered --workspace .workforge --item <id> --status doing`
+
+Continue using `discovered` with `status` and `complete-task` to keep the issue
+checklist synchronized.
+
+Never commit `.env` or `output/`. See the repository's contributor and agent
+guides for its development, validation, and pull request rules. See the
+[WorkForge README](https://github.com/Nanielito/workforge#quick-start) for `uv`
+installation, provider configuration, and the complete command reference.
+"""
+
+
 def _project_workspace_gitignore_block(workspace_path: Path) -> str:
     workspace_ref = workspace_path.name if workspace_path.is_absolute() else workspace_path.as_posix().rstrip("/")
     return f"{workspace_ref}/.env\n{workspace_ref}/output/\n"

{workforge-2.4.1 → workforge-2.5.0}/tests/test_init_workspace.py

@@ -6,6 +6,7 @@ from workforge.cli import (
     _env_example_template,
     _init_workspace,
     _project_workspace_gitignore_block,
+    _workspace_readme_template,
     _workspace_config_template,
 )
 
@@ -49,11 +50,17 @@ def test_init_workspace_creates_project_local_scaffold(tmp_path: Path) -> None:
     assert created == [
         workspace / "workforge.yaml",
         workspace / ".env.example",
+        workspace / "README.md",
         workspace / "output" / ".gitkeep",
     ]
     assert (workspace / "inbox").is_dir()
     assert (workspace / "output").is_dir()
     assert (workspace / ".env.example").read_text() == ""
+    assert (workspace / "README.md").read_text() == _workspace_readme_template()
+    assert "uvx workforge" in (workspace / "README.md").read_text()
+    assert "Start from a requirement" in (workspace / "README.md").read_text()
+    assert "Continue existing items" in (workspace / "README.md").read_text()
+    assert "https://github.com/Nanielito/workforge#quick-start" in (workspace / "README.md").read_text()
     assert "default_provider: test-provider" in (workspace / "workforge.yaml").read_text()