coulomb/can-you-assist
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs + chore(workplan): complete T06 and T07 for CYA-WP-0004 — final documentation polish and packaging debt registration

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-27 00:18:39 +02:00
parent 69de28b1fe
commit c0039c293a
3 changed files with 68 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
AGENTS.md
View File

@@ -167,11 +167,19 @@ First useful worker moves:
## Commands
```bash
# Recommended: Install from latest development code
# === Packaging & Installation (CYA-WP-0004) ===
# Recommended: Stay on latest development code
make dev-install
# Or manually:
# pip install -e ".[dev]"
# Build distribution packages (sdist + wheel)
make dist
# Prepare a release (tests + clean build)
make release-prep
# Verify a built wheel in isolation
make check-dist
# Run the assistant
cya "your natural language request here"
@@ -179,17 +187,12 @@ cya --help
cya --explain-context "show me what context would be collected"
# Memory features (0003)
cya retrospect # Guided reflection session to set goals & preferences
cya --explain-context "..." # See exactly which memory was activated (including from retrospection)
cya retrospect # Guided reflection session
# Memory is user-controlled and scoped
# Backing files: ~/.config/cya/memory/<scope>.json (plain JSON, fully editable)
cya "remember that I always want --short --branch on git status"
# Tests (safety + memory + activation + retrospection)
# Tests
python -m pytest tests/ -q
# Git / inspection (always useful)
# Git / inspection
git status --short
git log --oneline -5
rg --files
@@ -201,7 +204,8 @@ Current primary entry point: `cya` (after editable install).
Relevant workplans:
- `workplans/CYA-WP-0002-memory-integration-roadmap.md`
- `workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md` (current)
- `workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md`
- `workplans/CYA-WP-0004-dev-install-and-release-packaging.md` (current)
## Workplan Convention

39
README.md
View File

@@ -20,59 +20,42 @@ usable after `pip install -e .`:
## Installation
### Recommended: Install from Development Head (Latest Code)
### 1. Install from Development Head (Recommended for Daily Use)
This is the easiest way to stay on the absolute latest version while you work:
Stay on the absolute latest code with one command:
```bash
git clone https://github.com/worsch/can-you-assist.git
cd can-you-assist
# One-command developer install (includes dev tools)
make dev-install
# Or manually:
# pip install -e ".[dev]"
```
This installs the package in editable mode from your local checkout. You will always get the newest code when you pull.
After installation:
```bash
cya --help
cya --version # Will show a development version (e.g. 0.2.0.devN+g...)
```
### Alternative: Install Directly from Git (No Local Clone)
You can also install the latest code directly from GitHub without cloning first:
Or the direct git method (no permanent clone needed):
```bash
pip install "git+https://github.com/worsch/can-you-assist.git@main#egg=can-you-assist[dev]"
```
This is useful for quick testing or on remote machines.
After installing, `cya --version` will show a development version (e.g. `0.2.0.dev48+gf500a35...`).
### For Future Released Versions
### 2. Install a Released Version (Future)
Once we publish packages (future work), you will be able to do:
Once we publish official releases:
```bash
pip install can-you-assist
```
or a specific version:
```bash
# or a specific version
pip install "can-you-assist>=0.3.0"
```
### Updating to Latest Development Code
See `docs/release-process.md` for how releases are cut.
### Updating
```bash
cd can-you-assist
git pull
pip install -e ".[dev]" # or just `make dev-install`
make dev-install
```
## Usage examples

58
workplans/CYA-WP-0004-dev-install-and-release-packaging.md
View File

@@ -167,35 +167,43 @@ completed: "2026-05-27"
```task
id: CYA-WP-0004-T06
status: todo
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"
```
- 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.
**Done.**
**Acceptance criteria**:
- Both installation methods are clearly documented and discoverable by someone reading the README.
- 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: todo
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"
```
- 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.
**Done.**
**Acceptance criteria**:
- Packaging is no longer an afterthought — it has documented ownership and a path forward.
- `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
@@ -203,10 +211,26 @@ state_hub_task_id: "f4ea08ab-219e-4e7f-86b9-a05e27b8a72c"
- 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.
## Activation & Ralph Execution
## Debt & Future Work (Registered)
**Status: active** — activated for ralph-workplan loop execution (HEUREKA promise, max 20 iterations). This workplan addresses the practical gap where only editable development installs were supported, by enabling reliable installation from the development head and creating a repeatable process for versioning and building distribution packages.
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**: This workplan closes an important practical gap. It makes `cya` usable from the latest code for the primary user and creates the foundation for proper releases.
**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.