commitea/docs/PLAN.md

# CommiTea — AI-PM on Gitea

Plan file. Created 2026-07-07 from brainstorm session. Status: **pre-design** —
design session next, phases below get actuals as they complete.

## Concept

Lightweight project tracking/management system. Gitea = core engine for
milestones/tickets. Local-ish LLM agent acts as project manager: captures work
via interview, maps capacity, forecasts deadlines, adjusts priorities on
directives. Electron app, one window, "tell me what to do" experience.

## Goals (numeric where possible)

1. **Forecast honesty**: milestone forecasts as Monte Carlo cones (e.g. "80%
   land Mar 3–12"), never point dates. Calibration curve active after ≥20
   closed issues with estimates.
2. **Capture speed**: braindump → approved ticket set (estimates, deps,
   milestone) in < 2 min via agent interview.
3. **Responsiveness**: full gitea reconcile < 5 s @ 500 issues; scheduler +
   Monte Carlo run < 1 s @ 200 open issues; webhook-driven updates visible
   < 2 s.
4. **Agent economy**: hot context ≤ 2k tokens; works with a 4B local model for
   prose/ritual tasks (bigger model only for decomposition/negotiation).
5. **Zero pollution**: managed work repos gain only human-meaningful labels
   (`est/*`, `p/*`, `deadline/hard`) — no bot comments, no body frontmatter,
   no synthetic issues.

## Core architecture decisions (settled in brainstorm)

- **Purity rule**: gitea holds *human-authored intent* (issues, milestones +
  due dates, dependencies, assignees, labels, comments). Sidecar holds
  *machine-derived state* (forecasts, calibration, inferred lifecycle
  timestamps, capacity, agent memory). Test: delete sidecar → resync → no
  truth lost.
- **`pm-state` repo in gitea** = shared sidecar store. Versioned files;
  directive log is append-only JSONL (merges conflict-free). Local SQLite is
  a rebuildable cache/index only.
- **Estimates/priority visible in gitea** as fixed label sets: `est/1d 2d 3d
  5d 8d`, `p/1..4`; `deadline/hard` label on milestones (agent asks hard/soft
  at creation). Estimate unit = days.
- **LLM never does math.** Deterministic scheduler (code) computes forecasts,
  critical path, next-unit-of-work from estimates + deps + capacity +
  priority. Evidence-based scheduling: Monte Carlo over the team's own
  estimate-vs-actual history. LLM captures/negotiates inputs and explains
  outputs.
- **Lifecycle inference, no manual time tracking**: issue opened → diagnosis;
  labeled/milestoned → triage; first branch/commit ref → work start; PR
  merged → deploy; closed → complete. Timestamps from gitea events feed
  actuals.
- **Directives are first-class**: append-only log entry (who/when/what/why) →
  scheduler re-run → agent presents consequence diff ("X today, milestone Y
  +6d — accept?"). Directive-giver is a role; v1 = one PM (Stephen).
- **Model layer**: OpenAI-wire-protocol client, base-URL + model per role.
  Router: small local (gemma-4b class) for summaries/standup prose; big model
  (remote LM Studio box or OpenAI API) for decomposition/estimate
  negotiation. Few, fat tools (e.g. one `query_project`) so small models
  survive.
- **Agent conduct**: interview > dumping for capture; propose-approve for
  destructive ops, direct-act for additive; morning-standup ritual (drift
  report, today's plan, stale-blocker nagging).
- **Memory**: hot (charter + active directives + focus snapshot, ≤2k tok) /
  warm (append-only event log, weekly digests) / cold (gitea + sidecar via
  tools — ticket data never copied into memory). No graph in v1.
- **Sync**: per-instance gitea webhooks while running + full reconcile on
  launch + light poll fallback.
- **Multi-contributor v1**: gitea users as identities; per-person capacity =
  hours/day × focus factor + standing allocation slices (dev/compliance/
  pilots). Multi-*writer* (concurrent directive-givers) deferred.
- **Repos**: CommiTea source lives in its own repo (`commitea`) on
  gitea.stephenmann.io; targets N work repos via config (v1: one). Dogfood:
  CommiTea's own backlog is the first managed project.
- **Stack**: Electron + React + Tailwind (novelpad patterns), one window.

## UI (to be designed — design session)

- Hero: **Now/Next/Later focus card** — scheduler-picked next unit, agent's
  one-line rationale.
- **Burn-up with forecast cone** (ahead/behind as geometry), **runway view**
  (capacity vs milestone dates).
- Secondary drill-ins: dependency graph / Gantt, kanban.
- Chat = write-path (mutations via agent), UI = read-path. Exact split to be
  settled in design session.

## Phases

Deliverables per phase; replace TBD with actuals at phase close.

- **P0 — Scaffold** — repo, Electron shell, gitea API client + token auth,
  `pm-state` repo bootstrap. Actual: TBD
- **P1 — Sync + data model** — read mirror into SQLite cache, webhook
  listener + reconcile-on-launch, lifecycle inference from event stream,
  label schema applied. Actual: TBD
- **P2 — Scheduler + Monte Carlo** — deterministic forecast engine, capacity
  model, calibration store (cold-start: default distributions until n≥20),
  directive log + consequence diff. Actual: TBD
- **P3 — UI views** — focus card, burn-up cone, runway, drill-ins. Actual: TBD
- **P4 — Agent** — model router, fat tools, capture interview, propose-
  approve loop, standup ritual, memory layers. Actual: TBD
- **P5 — Dogfood + polish** — manage CommiTea with CommiTea; calibrate.
  Actual: TBD

(Order note: P3 before P4 so the agent has something to point at; thin
vertical slices within phases where possible.)

## Not doing (v1)

- Google Calendar capacity import (phase 2: free/busy read-only per member)
- Phone/push notifications
- Agent code review / PR content reading (PR *events* are in for lifecycle)
- Graph-structured agent memory
- PTO/meeting calendars
- Concurrent multi-PM directive writing
- Cloud LLM as *requirement* (it's a config option, not a dependency)

## Open items for design session

- Chat-as-only-write-path: strict or soft (UI edits allowed but agent
  observes/objects)?
- `pm-state` file formats (JSONL event log settled; capacity/calibration
  schemas TBD)
- Tool schema for the fat `query_project` tool
- Webhook endpoint mechanics per instance (port allocation, cleanup on quit)
- Cold-start estimate distributions (industry priors vs uniform pessimism)