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

---
id: CYA-WP-0004
type: workplan
title: "Developer Installation from Git and Release Distribution Packaging"
domain: agents
repo: can-you-assist
status: done
owner: grok
topic_slug: foerster-capabilities
created: "2026-05-27"
updated: "2026-05-27"
state_hub_workstream_id: "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

```task
id: CYA-WP-0004-T01
status: done
priority: high
state_hub_task_id: "018d0c4c-948e-4cd6-9a50-92a83725df18"
started: "2026-05-27 ralph iter 1"
completed: "2026-05-27"
```

**Done** — produced `docs/packaging-audit-and-requirements.md`.

- Full audit of `pyproject.toml` (static version in two places, minimal config, no extras, no modern build frontend).
- Documented gaps for both "install from dev head" and "release packaging".
- Clear requirements defined.
- Versioning strategy options analyzed (recommended: `setuptools_scm` hybrid for good dev-head versions + clean releases).

**Acceptance criteria met**:
- Gap analysis + requirements document created.
- Versioning options documented for decision in T02.

### T02 — Establish a sustainable versioning strategy

```task
id: CYA-WP-0004-T02
status: done
priority: high
state_hub_task_id: "0728680e-f9a9-4229-afcc-6c4d42d2e447"
started: "2026-05-27 ralph iter 2"
completed: "2026-05-27"
```

**Done** — implemented `setuptools_scm` hybrid approach.

- `pyproject.toml` now uses dynamic versioning with `setuptools_scm`.
- Added `src/cya/_version.py` (generated, gitignored).
- Updated `src/cya/__init__.py` to import `__version__` from the generated file (with fallback).
- Added `_version.py` to `.gitignore`.
- Dev-head installs will now produce versions like `0.2.0.devN+g<hash>`.
- Releases will be clean (once we tag).

**Acceptance criteria met**:
- Versioning is now dynamic and informative for dev-head installs.
- Clean path for future release versions.

### T03 — Make reliable installation from development head possible

```task
id: CYA-WP-0004-T03
status: done
priority: high
state_hub_task_id: "14e085dd-847a-4678-a1e4-abe5e3c369aa"
started: "2026-05-27 ralph iter 3"
completed: "2026-05-27"
```

**Done.**

- Added `[project.optional-dependencies]` `dev` and `test` in `pyproject.toml`.
- Created a simple but effective `Makefile` with:
  - `make dev-install` (recommended one-command dev-head install)
  - `make test`, `make dist`, `make version`, `make clean`
- Heavily updated README.md "Installation" section with clear instructions for:
  - Local dev-head install via Makefile
  - Direct `pip install "git+..."` from GitHub
  - Future released packages
- Updated AGENTS.md Commands section to reference the new `make dev-install` flow.
- With `setuptools_scm` from T02, git-based installs now produce proper development versions.

**Acceptance criteria met**:
- Primary user (and contributors) now have a simple, documented one-command path to install the absolute latest code from the development head.
- The installed version will clearly show it is a development version.

### T04 — Enable clean building of distribution packages

```task
id: CYA-WP-0004-T04
status: done
priority: high
state_hub_task_id: "d49a3362-865f-4397-b127-372a2aa2c4a2"
started: "2026-05-27 ralph iter 4"
completed: "2026-05-27"
```

**Done.**

- Created `MANIFEST.in` for proper sdist inclusion.
- Improved `pyproject.toml` (include-package-data, license-files under setuptools, package-data).
- `python -m build` successfully produces clean sdist + wheel.
- Verified in isolated venv: the wheel installs cleanly and `cya --version` works (shows proper dev version from setuptools_scm).

**Acceptance criteria met**:
- Clean, usable distribution packages can now be built.
- They install and run correctly in fresh environments.

### T05 — Create a lightweight release process

```task
id: CYA-WP-0004-T05
status: done
priority: medium
state_hub_task_id: "c97acc58-14d7-47b9-9ab3-936ab1eb92df"
started: "2026-05-27 ralph iter 5"
completed: "2026-05-27"
```

**Done.**

- Created `docs/release-process.md` — a clear, step-by-step, low-risk release checklist covering version decision → tests → build → tagging.
- Enhanced the `Makefile` with two very useful release targets:
  - `make release-prep` (runs clean + test + dist in one go)
  - `make check-dist` (smoke-tests the built wheel in a fresh venv)
- The process is fully reproducible and documented.

**Acceptance criteria met**:
- A maintainer now has a written checklist + Makefile helpers that make cutting a release feel safe and boring.
- The process produces ready-to-upload artifacts.

### T06 — Update documentation for both installation methods

```task
id: CYA-WP-0004-T06
status: done
priority: high
state_hub_task_id: "5a4dcdf8-7b0f-45cb-8eb1-46b0d60f8420"
started: "2026-05-27 ralph iter 6 (final docs)"
completed: "2026-05-27"
```

**Done.**

- Significantly polished the Installation section in README.md to clearly distinguish:
  - Development / bleeding-edge installs (via `make dev-install` or direct `git+`)
  - Future path for released versions
- Added references to `docs/release-process.md`
- Updated AGENTS.md "Commands" section with packaging-related Makefile targets and the current workplan reference.

**Acceptance criteria met**:
- Both installation methods are now clearly documented and easy to discover in the README.

### T07 — Register packaging as a first-class concern

```task
id: CYA-WP-0004-T07
status: done
priority: medium
state_hub_task_id: "f4ea08ab-219e-4e7f-86b9-a05e27b8a72c"
started: "2026-05-27 ralph iter 7 (final)"
completed: "2026-05-27"
```

**Done.**

- `make check-dist` already exists and is promoted as the packaging verification step.
- Added a clear "Debt & Future Work (Registered)" section in the workplan itself, explicitly listing PyPI publishing, automated releases, package signing, CI gates, and multi-Python testing as tracked items in State Hub.
- Packaging is now treated as a first-class, owned concern with documented ownership and a clear path forward.

**Acceptance criteria met**:
- Packaging is no longer an afterthought — it has documented ownership, verification tooling, and registered future work in State Hub.

## 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.

## Debt & Future Work (Registered)

This workplan explicitly registers the following as first-class technical debt / extension points:

- PyPI publishing workflow
- Automated releases via CI on tags
- Package signing
- Adding `make check-dist` (or equivalent) as a required CI gate
- Multi-Python version testing for distribution packages

These are now tracked in State Hub via this workplan.

## Completion

**Status: done** — all tasks completed via ralph loop.

This workplan successfully delivered reliable dev-head installation, dynamic versioning, clean distribution package building, a lightweight release process, and clear documentation for both use cases.

Packaging is now a first-class, owned concern in the project with a documented path forward.

---

**Status note**: CYA-WP-0004 is complete. The project has moved from "only editable install" to having a full, practical story for both bleeding-edge development installs and future proper releases.