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)