Design spike: issue-triggered project AI wakeup + tmux session convention #28

New Issue

Closed

opened 2026-07-13 13:44:50 +00:00 by jared · 1 comment

jared commented

2026-07-13 13:44:50 +00:00

Owner

What to build

Design-spike / HITL. The automation stage beyond cross-project filing (#27): when an issue is filed with a project, that project's AI is awakened to triage or act on it.

Questions the spike must answer (outcome is an ADR + a thin pilot, not a full build):

Trigger: Forgejo webhooks vs polling (a cron/heartbeat scanning tracked repos for new issues via tea). Polling is likely the simpler, host-agnostic first cut; webhooks need a listener endpoint.
Execution surface: headless (claude -p / Agent SDK) vs a tmux session the human can attach to, inspect, and take over. Related: establish a general tmux session convention (naming scheme per project, lifecycle, when an AI-run session is created/kept/killed, how a human discovers running sessions) — this convention is useful beyond issue-wakeup and should be its own ADR section or ADR.
Autonomy guardrails: reuse the hitl/semi/afk-ready vocabulary (ADR-0029) — an awakened AI acts only on issues labeled for autonomous work; everything else is triage-and-notify. Notification policy v2 applies.
Safety/scope: which projects opt in, credential handling (never read ~/.credentials contents), and how the wakened session gets the Discoverer/session-id context from #27's template.

Acceptance criteria

ADR (or ADR pair: wakeup mechanism + tmux convention) recording the design, human-approved
Thin pilot demonstrated on one project (e.g. poll → new afk-ready issue → session spawned → triage comment posted)
Explicit non-goals recorded (what stays manual)

Blocked by

#27 (global project index + filing convention — supplies the registry and metadata contract)

Discoverer: jared/cc-os session 5b0af6f9-ee11-4f48-b497-f971a7c7c298, 2026-07-13.

## What to build Design-spike / HITL. The automation stage beyond cross-project filing (#27): when an issue is filed with a project, that project's AI is awakened to triage or act on it. Questions the spike must answer (outcome is an ADR + a thin pilot, not a full build): 1. **Trigger**: Forgejo webhooks vs polling (a cron/heartbeat scanning tracked repos for new issues via `tea`). Polling is likely the simpler, host-agnostic first cut; webhooks need a listener endpoint. 2. **Execution surface**: headless (`claude -p` / Agent SDK) vs a **tmux session** the human can attach to, inspect, and take over. Related: establish a general **tmux session convention** (naming scheme per project, lifecycle, when an AI-run session is created/kept/killed, how a human discovers running sessions) — this convention is useful beyond issue-wakeup and should be its own ADR section or ADR. 3. **Autonomy guardrails**: reuse the hitl/semi/afk-ready vocabulary (ADR-0029) — an awakened AI acts only on issues labeled for autonomous work; everything else is triage-and-notify. Notification policy v2 applies. 4. **Safety/scope**: which projects opt in, credential handling (never read ~/.credentials contents), and how the wakened session gets the Discoverer/session-id context from #27's template. ## Acceptance criteria - [ ] ADR (or ADR pair: wakeup mechanism + tmux convention) recording the design, human-approved - [ ] Thin pilot demonstrated on one project (e.g. poll → new afk-ready issue → session spawned → triage comment posted) - [ ] Explicit non-goals recorded (what stays manual) ## Blocked by - #27 (global project index + filing convention — supplies the registry and metadata contract) --- **Discoverer:** jared/cc-os session 5b0af6f9-ee11-4f48-b497-f971a7c7c298, 2026-07-13.

jared commented

2026-07-13 15:03:50 +00:00

Author

Owner

Spike complete in 43932d4, both ADRs Accepted at the human gate (2026-07-13): ADR-0035 (wakeup via polling — opt-in wakeup=true in .cc-os/config, per-repo last-seen state, afk-ready→act / semi→triage-only / else pull-only notify, explicit non-goals recorded) and ADR-0036 (tmux convention cc--[-], kill-after-clean-completion, keep-on-error/hitl). Thin pilot bin/wakeup-poll demonstrated: real-index dry run correctly skipped cc-os (planka: tracker), synthetic forgejo project correctly detected issue #28 as new and classified it notify-only. No cron installed. Follow-up recorded: single designated poller machine; cadence + config-write wakeup key deferred to first opt-in project. Closing — acceptance criteria met (ADRs approved, pilot demonstrated, non-goals recorded).

Spike complete in 43932d4, both ADRs Accepted at the human gate (2026-07-13): ADR-0035 (wakeup via polling — opt-in wakeup=true in .cc-os/config, per-repo last-seen state, afk-ready→act / semi→triage-only / else pull-only notify, explicit non-goals recorded) and ADR-0036 (tmux convention cc-<project>-<purpose>[-<n>], kill-after-clean-completion, keep-on-error/hitl). Thin pilot bin/wakeup-poll demonstrated: real-index dry run correctly skipped cc-os (planka: tracker), synthetic forgejo project correctly detected issue #28 as new and classified it notify-only. No cron installed. Follow-up recorded: single designated poller machine; cadence + config-write wakeup key deferred to first opt-in project. Closing — acceptance criteria met (ADRs approved, pilot demonstrated, non-goals recorded).