tegwick
63a66b708a
Some checks failed
tamq-ci / test (push) Failing after 5s
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc
133 lines
4.2 KiB
Markdown
133 lines
4.2 KiB
Markdown
---
|
|
id: TAMQ-WP-0004
|
|
type: workplan
|
|
title: "Operator-installable local alpha session"
|
|
domain: communication
|
|
repo: tmux-amq
|
|
status: ready
|
|
owner: codex
|
|
topic_slug: coulomb-social
|
|
planning_priority: P0
|
|
planning_order: 10
|
|
created: "2026-08-24"
|
|
updated: "2026-08-24"
|
|
---
|
|
|
|
# Operator-installable local alpha session
|
|
|
|
Make tmux-amq directly usable by the operator from a normal local shell without
|
|
running it from the source checkout or manually assembling service, tmux, and
|
|
agent commands.
|
|
|
|
## Alpha user journey
|
|
|
|
The completed workflow must be:
|
|
|
|
```bash
|
|
git clone <tmux-amq-remote>
|
|
cd tmux-amq
|
|
make install
|
|
|
|
tamq --version
|
|
tamq start tmux-amq
|
|
```
|
|
|
|
`tamq start tmux-amq` starts or reuses the local service and managed `tamq`
|
|
session, opens the `tmux-amq` gita repository in its registered path, launches
|
|
Codex behind `tamq tap`, and attaches the operator to the session. The detached
|
|
workflow must also work:
|
|
|
|
```bash
|
|
tamq start --detach tmux-amq
|
|
tamq status
|
|
tamq attach
|
|
```
|
|
|
|
## Acceptance gates
|
|
|
|
- `make install` is documented, repeatable, and installs an isolated `tamq`
|
|
command into the invoking user's normal executable path.
|
|
- Installation and upgrade do not require activating the repository `.venv`.
|
|
- Missing `uv`, tmux, gita, Codex, PATH configuration, or repository
|
|
registration produces a direct actionable error before a partial session is
|
|
left behind.
|
|
- The first and subsequent windows start in their exact `gita freeze` paths.
|
|
- Default `tamq start` attaches; `--detach` returns to the caller and prints a
|
|
useful endpoint/session summary; `tamq attach` attaches later.
|
|
- Repeating `tamq start` safely reuses the service/session and does not create
|
|
duplicate repository windows or agent processes.
|
|
- A real installed-package smoke test proves start, attach/detach, status,
|
|
message routing, history visibility, stop, and bounded cleanup on this local
|
|
environment.
|
|
- The README contains a short install/start/stop/uninstall quickstart and states
|
|
the alpha reliability boundaries from `SCOPE.md`.
|
|
|
|
## Add the user-level install target
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T01
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Add a phony `make install` target using uv's isolated tool installation flow,
|
|
with an explicit upgrade/reinstall behavior suitable for repeated development
|
|
installs. Verify `command -v tamq`, `tamq --version`, and invocation from outside
|
|
the checkout. Document the corresponding uninstall command and executable-path
|
|
expectation.
|
|
|
|
## Make session startup match the CLI contract
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T02
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Implement the currently unused `--detach` flag. Make non-detached `tamq start`
|
|
attach to the managed session after successful endpoint registration and pending
|
|
delivery. Ensure the first boot window uses the selected repository's registered
|
|
path rather than the caller's current directory, and preserve idempotent reuse of
|
|
existing windows.
|
|
|
|
## Add installation and startup preflight
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T03
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Before mutating tmux or service state, check the required commands, exact gita
|
|
targets and paths, writable runtime/state locations, agent command availability,
|
|
and session conflicts. Return concise remediation for every failure and avoid
|
|
leaving boot windows, sockets, pidfiles, or processes behind after a failed
|
|
start.
|
|
|
|
## Prove the installed local session end to end
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T04
|
|
status: wait
|
|
priority: high
|
|
```
|
|
|
|
Add automated coverage using an isolated uv tool directory, state directory,
|
|
socket, and tmux server. Use a deterministic benign agent fixture in automation,
|
|
then perform the operator acceptance with the installed `tamq` command and Codex.
|
|
Prove attach/detach semantics, correct pane directories, idempotent reuse,
|
|
message injection/history, shutdown, and cleanup. This task follows T01-T03.
|
|
|
|
## Publish the alpha quickstart and evidence
|
|
|
|
```task
|
|
id: TAMQ-WP-0004-T05
|
|
status: wait
|
|
priority: medium
|
|
```
|
|
|
|
Update README and agent workflow documentation with prerequisites, install,
|
|
upgrade, start, attach, status, stop, and uninstall commands. Record the exact
|
|
local acceptance commands and results. Clearly retain the reliability caveats
|
|
owned by `TAMQ-WP-0003` and do not claim coordination-engine integration from
|
|
`TAMQ-WP-0002`. This task follows T04.
|