can-you-assist/workplans/CYA-WP-0004-dev-install-and-release-packaging.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CYA-WP-0004	workplan	Developer Installation from Git and Release Distribution Packaging	capabilities	can-you-assist	proposed	grok	foerster-capabilities	2026-05-27	2026-05-27	7913b919-d76b-4374-bdc6-0330fe941666

CYA-WP-0004: Developer Installation from Git and Release Distribution Packaging

Goal

Enable two important installation and distribution experiences for can-you-assist (cya):

1. Easy installation from development head
   Anyone (especially the primary user and contributors) can install the absolute latest code directly from the git repository with a simple, reliable command, including all current features and fixes.

2. Repeatable release packaging
   Provide a clear, low-friction process to cut versions and produce installable distribution packages (sdist + wheel) that others can use via pip install without needing to clone the repository or understand the development setup.

This workplan addresses the current gap where only pip install -e . (editable development install) is supported, and there is no documented or automated path for either "bleeding edge" installs or proper releases.

Background & References

• Current packaging is minimal (pyproject.toml using setuptools with a static version = "0.1.0").
• Editable development install (pip install -e .) works and is documented in README and AGENTS.md.
• No support yet for pip install git+https://... in a robust way.
• No versioning strategy, no release process, no build frontend usage, and no distribution artifacts.
• The project has matured through CYA-WP-0001 (MVP), 0002 (Memory), and 0003 (Contextual Activation + Retrospection), making proper distribution increasingly important.
• AGENTS.md and README currently only document the editable development path.

Non-Goals (for this slice)

• Publishing packages to PyPI (the output of this workplan should be usable with a future PyPI publication step).
• Complex multi-platform CI matrix or release automation beyond a solid local + basic CI foundation.
• Supporting ancient Python versions or exotic packaging backends.
• Creating a full "release engineering" platform (this is scoped to getting reliable dev-head + released packages working).

Task Breakdown

T01 — Audit current packaging state and define requirements

id: CYA-WP-0004-T01
status: todo
priority: high
state_hub_task_id: "018d0c4c-948e-4cd6-9a50-92a83725df18"

• Review the current pyproject.toml, src/ layout, entry points, and any hidden packaging assumptions.
• Document what currently works and what breaks for:
  • pip install git+https://...
  • Building clean sdist + wheel
• Define concrete requirements for both "dev head" and "released package" experiences.
• Decide on a versioning approach (e.g., static + manual bumps, setuptools_scm, or hybrid).

Acceptance criteria:

• Clear gap analysis and requirements document (can live in the workplan or a short docs/packaging-requirements.md).
• Versioning strategy chosen and justified.

T02 — Establish a sustainable versioning strategy

id: CYA-WP-0004-T02
status: todo
priority: high
state_hub_task_id: "0728680e-f9a9-4229-afcc-6c4d42d2e447"

• Implement the chosen versioning approach in pyproject.toml.
• For development head installs, ensure versions are informative (e.g., 0.2.0.devN+g1234567 or similar).
• For releases, ensure clean, sortable versions.
• Document how to bump versions (manual or scripted).

Acceptance criteria:

• Both pip install -e . and pip install git+... produce sensible versions.
• A documented, low-friction way exists to prepare a new release version.

T03 — Make reliable installation from development head possible

id: CYA-WP-0004-T03
status: todo
priority: high
state_hub_task_id: "14e085dd-847a-4678-a1e4-abe5e3c369aa"

• Ensure pip install "git+https://github.com/worsch/can-you-assist.git" (and branch variants) works cleanly.
• Add any necessary [project.optional-dependencies] (e.g., dev, test).
• Create a recommended one-liner or short documented flow for the primary user.
• Optionally add a Makefile target (e.g., make dev-install) as a convenience.

Acceptance criteria:

• A non-developer can successfully install the latest code from git with one command and get a working cya binary.
• The installed version clearly indicates it is from development head.

T04 — Enable clean building of distribution packages

id: CYA-WP-0004-T04
status: todo
priority: high
state_hub_task_id: "d49a3362-865f-4397-b127-372a2aa2c4a2"

• Adopt the modern build frontend (python -m build).
• Ensure pyproject.toml + package data produces high-quality sdists and wheels.
• Add or improve MANIFEST.in / pyproject.toml configuration so that necessary files (README, LICENSE, etc.) are included.
• Verify that the resulting packages can be installed in a fresh environment and provide a working cya command.

Acceptance criteria:

• python -m build produces a clean sdist and wheel.
• The wheel installs correctly and cya --version works in an isolated environment.

T05 — Create a lightweight release process

id: CYA-WP-0004-T05
status: todo
priority: medium
state_hub_task_id: "c97acc58-14d7-47b9-9ab3-936ab1eb92df"

• Document (and optionally script) the steps to cut a release:
  1. Decide on new version
  2. Update version metadata
  3. Run tests
  4. Build packages
  5. Create git tag
• Consider a small helper script or Makefile targets (make release-prep, make build-dist).
• Ensure the process is reproducible and documented in a docs/release-process.md or similar.

Acceptance criteria:

• A clear, written release checklist or script exists that a maintainer can follow with low risk of mistakes.
• The process produces artifacts that could be uploaded to a package index.

T06 — Update documentation for both installation methods

id: CYA-WP-0004-T06
status: todo
priority: high
state_hub_task_id: "5a4dcdf8-7b0f-45cb-8eb1-46b0d60f8420"

• Update README.md with clear sections for:
  • Development / bleeding-edge install (from git)
  • Installing a released version (when available)
• Update AGENTS.md "Commands" section.
• Add any necessary notes in the new workplan or a dedicated packaging guide.

Acceptance criteria:

• Both installation methods are clearly documented and discoverable by someone reading the README.

T07 — Register packaging as a first-class concern

id: CYA-WP-0004-T07
status: todo
priority: medium
state_hub_task_id: "f4ea08ab-219e-4e7f-86b9-a05e27b8a72c"

• Add basic packaging verification to the development workflow (e.g., make check-dist or a CI step).
• Document known limitations and future improvements (e.g., PyPI publishing, automated releases, signed packages).
• Register this area as an extension point / debt item in State Hub via the workplan.

Acceptance criteria:

• Packaging is no longer an afterthought — it has documented ownership and a path forward.

Dependencies & Cross-Repo Coordination

• No hard external dependencies on other tracked repositories for the core work.
• Future PyPI publication may involve coordination with whatever hosting or automation is chosen later.
• State Hub will be used to track the workplan and any packaging-related decisions or debt.

Proposed Status & Activation

This workplan is created in proposed status. It should be reviewed, moved to ready, and activated when the team is ready to invest in making cya easily installable both for the primary user (from dev head) and for potential future users/contributors via proper packages.

---

Status note: This workplan closes an important practical gap. Until now the project has been developed in a "works on my machine via editable install" mode. This workplan makes the tool usable by its primary user from the latest code and creates the foundation for others to consume it as a normal Python package.