coreci-chat/.ciagent/PROJECT.md

coreci-chat

What This Is

A browser-based chat interface where mid-market enterprise IT operators ask natural-language questions about their infrastructure (Proxmox VE 7.x/8.x, SSH/Linux servers on Ubuntu 24.04 LTS / Debian 12+, GitHub, self-hosted Gitea) and receive coherent, evidence-backed diagnostic answers within 5 minutes (p95). All LLM inference is routed through a customer-provided model endpoint (BYOM) — CoreCI Chat never hosts inference. CoreCI Chat is a companion product to CoreCI (the owner's existing CI/CD platform). The v0.1 wedge is deliberately conservative: investigate and diagnose; remediation is deferred to v1.1.

The Relay Agent is a lightweight systemd service installed on customer Linux hosts, communicating to the CoreCI Chat SaaS over an outbound-only WebSocket. Read-only enforcement is applied at both the MCP gateway (control plane) and the Relay Agent (SSH command whitelist). Every prompt, tool call, SSH command, and response is written to an immutable audit log. All tenant-scoped data is protected by Postgres Row-Level Security. All credentials live in a centralized secret manager (AWS Secrets Manager in prod, encrypted-local fallback in dev).

One-sentence goal: A browser-based chat interface where mid-market enterprise IT operators ask natural-language questions about their infrastructure (Proxmox, SSH/Linux servers, GitHub, Gitea) and receive evidence-backed diagnostic answers in under 5 minutes — with all LLM inference routed through customer-provided model endpoints (BYOM).

Milestone

v0.1 — Read-Only Diagnostic MVP. Milestone branch: milestone/v0.1-bootstrap. Tags run on the v0.0.x patch line (no prior minor exists); phase 0 seeds v0.0.1, each execution phase ships a progressive patch, and the final phase's patch (v0.0.(N+1)) IS the milestone release. Milestone type: Feature (at least one feat: phase).

Authoritative Spec

/home/opencode/coreci-chat/.ciagent/steer-v0.1-spec.md — CoreCI Chat v0.1 Engineering Specification v1.1 (FINAL), authored by Sarah Chen (Product Owner), locked 2026-08-24. Anchor docs: CoreCI Chat Vision v1.0, locked Phase 2 scope decisions. All 44 REQs locked; Section 7 decisions locked.

M1 Scope (current milestone)

REQ-001 → REQ-014, REQ-038, REQ-039, REQ-040 (17 REQs total). M1 acceptance gate (spec §2.3): Platform Lead can sign up via SSO, configure a BYOM endpoint with green validation, deploy Relay Agent via install script on at least one target Linux host, register the target, and see green status in the admin dashboard. Audit logging, RLS, and secret manager are operational.

Requirements

Validated (Phase 0 init)

• ✓ Initialize a git repository at ~/coreci-chat with branch hierarchy main → milestone/v0.1-bootstrap → phase/00-pre-execution
• ✓ Write .ciagent/config.json with autonomy full, release target Gitea coreci/coreci-chat, secrets hygiene
• ✓ Persist GITEA_TOKEN to .ciagent/.env.secrets (mode 0600); .env* in .gitignore

Active (Phase 0 — this run)

• SPECIFY: parse spec, rewrite PROJECT.md / REQUIREMENTS.md / ARCHITECTURE.md with real content
• CLARIFY: resolve 5 architectural decisions (approved by PO during kickoff)
• RESEARCH: produce research artifacts + PERSONAS.md under .ciagent/
• PLAN: vertical-slice wave plans referencing REQ IDs, MVP/UX sections
• GRILL: adversarial plan review, binding verdicts

Out of Scope (v0.1 — do not build)

See .ciagent/REQUIREMENTS.md § Out of Scope and spec §2.2. Highlights: write actions, hosted LLM inference, Kubernetes/ArgoCD/Helm, Slack/Teams/CLI/mobile, approval-gated remediation, RAG, SOC 2 Type 1 final cert, custom RBAC roles, BYOK, multi-region, Windows. Anything not in the spec is a spec-time scope question — never silently added.

Constraints

• Branch discipline: all writes on phase/NN-* branches, never main. ---ci--- blocks in every commit.
• Read-only by default: 100% of write-action requests rejected at MCP gateway (HTTP 403) and at Relay Agent (SSH whitelist). No state mutation is possible in v0.1.
• BYOM mandatory: 100% of LLM inference outbound to the customer-configured endpoint; zero inference from CoreCI Chat infra.
• Multi-tenancy isolation: Postgres RLS on all tenant-scoped tables; cross-tenant queries return empty. Quarterly pen test, zero leakage.
• Audit immutability: write-once store, 100% capture, zero deletes; write failure halts the operation (no silent drops).
• Secret handling: every credential via the centralized secret manager from the first secret. No env vars, no config files, no DB columns. Never logged in plaintext.
• RBAC enforcement: at the API gateway from the first endpoint. No "auth later" stubs.
• SSH whitelist: fixed whitelist shipped with the Relay Agent in M1; M2 plugs the SSH adapter into the existing enforcement hook. Customer extension deferred to v1.1 (signed config).
• Supported targets: Ubuntu 24.04 LTS, Debian 12+ (install script aborts cleanly on unsupported OS with actionable error). Proxmox VE 7.x and 8.x.
• Relay Agent distribution: install script (curl|bash) primary, apt package fallback. systemd service, outbound-only WebSocket, per-target registration.
• Async durable execution: Trigger.dev.
• Identity: WorkOS (SSO/SAML + SCIM).
• GRC: Vanta (instrumentation in M3, not M1).
• Single region: us-east-1 MVP. TLS 1.2+ in transit, AES-256 at rest.
• Performance NFRs: <3s p95 time-to-first-token; <5 min p95 diagnostic completion (≤10 tool calls); ≥5 concurrent workflows per tenant; ≤20 tool calls per workflow; 60 req/min per user, 300 req/min per tenant (token bucket).
• Autonomy: full — no HITL after clarify. Decision threshold 0.6. Escalation hooks: [deploy, delete_data, merge_to_main].

Key Decisions

Decision	Rationale	Source
Spec v1.1 locked, 44 REQs	Sarah Chen (PO) locked 2026-08-24	spec §8
M1 = REQ-001..014 + 038/039/040	spec §2.3	spec §2.3
Trigger.dev durable runtime	Best TS DX, long-running workflows, MVP cost	spec §7 Q1
WorkOS IdP	Enterprise SAML/SSO/SCIM at mid-market price	spec §7 Q2
Vanta GRC	AWS-native ecosystem, M3 instrumentation	spec §7 Q3
Install script primary, apt fallback	Fastest to ship, flexible	spec §7 Q4
Fixed SSH whitelist, no customer extension in v0.1	Security; signed-config extension in v1.1	spec §7 Q5
PVEAuditor built-in role for Proxmox	Simpler setup, well-understood	spec §7 Q6
Gitea via SaaS-to-API exposure	Customer opens firewall; Relay-Agent variant deferred	spec §7 Q7
pgvector for v1.1 RAG	Co-located with primary DB (not v0.1)	spec §7 Q8
OpenAI-compatible BYOM contract for M1	Most customer endpoints speak it; pluggable provider iface for Anthropic-native in M3	CLARIFY (PO-approved default)
Relay Agent in Go	Single static binary, ideal for curl|bash + systemd + zero-runtime on Ubuntu/Debian	CLARIFY (PO-approved default)
AWS Secrets Manager (prod) + local-encrypted (dev) behind SecretProvider interface	Spec §5 default us-east-1; interface enables CI/local without AWS	CLARIFY (PO-approved default)
Postgres append-only table + hash-chain + REVOKE UPDATE/DELETE for audit (M1); S3 Object Lock WORM in M3	Append-only from day one; cheap refactor to WORM later	CLARIFY (PO-approved default)
Next.js (App Router) + TypeScript single SPA	Dashboard in M1, chat UI in M3, same app	CLARIFY (PO-approved default)