SemTeams

An always-on program manager for a configurable portfolio, built on the semstreams framework.

SemTeams observes work across programs and projects, explains what changed, identifies where attention is needed, and helps an operator carry approved actions through. Research, planning, and design are supporting capabilities of that program manager, not separate product identities. The target product and MVP boundary are defined in docs/product/program-manager.md.

The current repository is the early product shell — UI, configs, personas, rules, internal/runtimecatalog, and a small set of product-shell tools — proving the multi-agent runtime on top of SemStreams. It has no custom Go components: every processor (graph, rule, agentic-dispatch, agentic-loop, agentic-model, agentic-tools, …) is imported from the upstream framework.

The approved next architecture assigns the agent runtime to SemTeams, the shared substrate and generic durability to SemEngine, and absorbs SemDev as a separately qualified development pack. That is a migration direction, not shipped behavior. The dev workflow retains issue → OpenSpec → implementation → verification → PR. See ADR-061 for ownership, observable-work goals and limits.

If you are looking for the framework itself (component model, knowledge graph, NATS streams, GraphQL gateway), see semstreams. This README covers what SemTeams adds on top.

┌─────────────────────────────────────────────────────────────┐
│                       SemTeams                              │
│  Svelte UI · configs · personas · rules · product tools     │
├─────────────────────────────────────────────────────────────┤
│              semstreams (Go module dependency)              │
│  components · graph · rule engine · agentic loop · NATS     │
└─────────────────────────────────────────────────────────────┘

What SemTeams adds

Surface	Path	What it is
Web UI	ui/	Svelte 5 + SvelteKit 2 chat / graph explorer / runtime monitor
Bootstrap config	configs/flow-bootstrap.json	Production substrate-plus-overlays wiring; mock-LLM clone at e2e-flow-bootstrap.json
Category packs	configs/rules/<category>/	Live: research/ (MVP supporting capability) and autoresearch/ (retained framework demonstration). Support: coordinator/, agent-run/, and ops/. Parked dev packs are donor material; see ADR-058. New task classes add a pack, not a component.
Personas	configs/personas/fragments/<role>/*.md	Role-specific prompt fragments loaded by the category packs. See configs/README.md for the current inventory.
Product tools	cmd/semteams/tools/	Tool executors that don't belong upstream: source ingest, artifact/spec emission, proof analysis/projection, sandbox bootstrap, and pack-specific measurement emitters.
Runtime catalog	internal/runtimecatalog/	Explicit frozen component and payload registration surface shared by cmd/semteams and cmd/openapi-generator.
Product shell	cmd/semteams/main.go	~600 LoC binary that wires the framework primitives directly for this product shell

Current agentic-* processors, the rule engine, graph and NATS wiring remain in SemStreams. internal/runtimecatalog makes the complete frozen component/payload registration surface explicit for the runtime and generators; it does not activate extra components or packs.

Frozen framework migration

SemTeams pins SemStreams v1.0.0-beta.162.0.20260930150212-8b99efe9c66a (SHA 8b99efe9c66a4faa4fa509f9f62cc6bad8392128). The upgrade from beta.160 landed in PR #281. Its migration evidence records the compatibility changes, independent reviews and final mock browser matrix: 24 active passes and five explicit skips. The autoresearch terminal-delivery blocker was repaired and qualified; the retained evidence also names the remaining product and recovery limits.

Use fresh, isolated NATS and graph state for this migration. Canonical entity identity and approval markers changed; retained beta.160 state conversion is not implemented. This instruction does not authorize deleting production data. SemSource-backed dogfooding waits for SemSource readiness. A later SemEngine switch needs its own approved consumer contract; dependency measurements do not expand SemEngine's first release automatically.

Run it

Prereqs

go version          # 1.26.3
docker info         # daemon running
node --version      # 22.20.0 for UI / Playwright journeys
task --version      # go install github.com/go-task/task/v3/cmd/[email protected]
caddy version       # required only for the live local UI path: task dev:research

No-key demo qualification

task ui:test:e2e:agentic:demo-mvp

That runs the black-box mock-LLM evidence pack for the demo contracts: coordinator routing, the reviewed research arc (single-branch and parallel fan-out/join), and fail-closed readiness before execution routing. It uses the dockerized e2e stack and requires no LLM API keys or host Caddy install. The autoresearch pack remains wired as an opt-in framework demonstration (task ui:test:e2e:agentic:autoresearch), not part of the MVP claim or required demo-mvp gate. Inspect each run's results and explicit skips before making a claim about that run.

Live chat UI

Copy .env.example to .env and set a live model key. The default production registry uses Gemini Flash, with Gemini Pro preferred for coordinator work and Anthropic endpoints available as fallbacks / alternatives:

cp .env.example .env
# edit .env, uncomment GEMINI_API_KEY=...

task dev:research

That boots NATS, builds and starts bin/semteams against configs/flow-bootstrap.json (the production bootstrap), then starts the UI proxy. Open http://localhost:3001 and type a prompt. You can chat with the coordinator first: ask what SemTeams can do, refine a rough idea, or ask which team fits. When the request is ready, the coordinator classifies it and routes it to one of the live category packs:

• a research question (compare X vs Y, how does Z work) → the research arc (MVP supporting capability);
• an optimize-a-metric ask (make this faster / smaller) → the autoresearch iteration loop, in a sandbox (retained framework demonstration, not part of the program-manager MVP claim).

Power users can prefix a prompt with /research or /optimize. Those are coordinator-routed hints, not bypasses; SemTeams still validates the prompt shape and keeps the usual sandbox and review gates.

Spec-authoring and software-implementation asks are currently parked, not live routes. The coordinator answers them honestly instead of dispatching create-change, proof-readiness, dev-from-task, or dev-via-test. Those packs remain on disk as donor material. SemDev currently implements the issue-to-PR journey; its future absorption under ADR-061 requires separate qualification. Do not reintroduce parked packs as a shortcut to that transfer or to program-manager action. See ADR-058.

Research results retain recoverable source evidence, but the current UI does not render the evidence bodies needed by ArtifactCard or artifact-context handoff. GraphQL exposes trajectory previews and StorageReference values; an authorized evidence-fetch pass must land before copy, attach, context-chip, or cross-team artifact reuse can be claimed live. ADR-059 records this accepted regression; issue #261 owns restoration.

See docs/architecture.md for what each pack does and how the sandbox is created.

task dev:stop tears it down.

Other useful starting points

You want	Run	Notes
No-key demo qualification	task ui:test:e2e:agentic:demo-mvp	Black-box Playwright + mock-LLM evidence pack. No API keys.
Live chat UI	task dev:research	Needs GEMINI_API_KEY for the default model registry; BRAVE_SEARCH_API_KEY recommended for web search.
Research arc proof	task ui:test:e2e:agentic:research-mvp	Mock-LLM plan/fan-out/join/synthesize/review journey.
Autoresearch framework demo (opt-in)	task ui:test:e2e:agentic:autoresearch	Retained framework demonstration of sandboxed metric iteration (not part of demo-mvp); final user delivery qualified in the frozen migration.
Coordinator routing proof	task ui:test:e2e:agentic:coordinator-routing-matrix	Includes honest responses for parked team asks.

task --list shows everything.

Find your way around

• You are running a journey and want to debug it → docs/getting-started.md. What the ports are, how to tail logs, how to inspect KV, how to abort a wedged loop.
• You want to know what the demo can honestly claim → docs/demo-mvp-claims.md. Supported claims, non-claims, black-box evidence rules, and MAVLink-hard scope.
• You want to know how prompts move through teams → docs/architecture.md. Coordinator routing, category packs, artifacts, gates, and sandbox handoff.
• You want to extend the product shell with a new tool, rule, persona, or KV bucket → read cmd/semteams/tools/README.md first. There is a mandatory framework-alignment review before adding to the shell — the semspec accretion lesson.
• You want different product composition → edit the bootstrap config and category packs, then restart. /admin/flows shows read-only admitted composition; runtime saved-flow authoring/deployment is retired.
• You want framework concepts (graph, rules, NATS streams, Graphable, payload registry) → upstream semstreams docs. This repo doesn't re-document them.

Develop

task build              # Build bin/semteams
task check              # Go lint + test (fast, no Node)
task check:all          # + UI lint + type-check + test + build

task ui:dev             # Vite dev server (UI only)
task ui:test:e2e        # Playwright E2E (auto-manages Docker stack)

task schema:generate    # Regenerate schemas/ + specs/openapi.v3.yaml

The Repository CI workflow runs on every non-draft pull request to main. Its Go, UI, and Governance jobs feed the always-reported Required aggregate. The Governance job strictly validates ATeam multi-agent parity and OpenSpec (openspec validate --all --strict, then ateam state spec-check). The separate Merge check workflow runs ateam review gate from the base commit. A draft pull request skips both. The live main branch ruleset (main-required-checks) requires Required and Merge check with strict up-to-date (strict_required_status_checks_policy=true) and squash-only PR merges, while required mock E2E in CI remains future work.

Before pushing:

task lint
task test:race
task test:integration
go build ./...
task schema:generate && task schema:check-changes
task openspec:validate

See CLAUDE.md for the deeper project context — config layering, product-shell wiring map, mandatory protocols (reviewer-pass, framework-alignment, E2E active monitoring).

Status

Active development. Breaking changes expected. The current runtime is not yet the program-manager MVP: today the live product-facing packs are research (MVP supporting capability) and autoresearch (retained framework demonstration). The next product slice is a read-only, evidence-backed program pulse across operator-configured projects and repositories; see the roadmap.

Current architecture is substrate-plus-overlays: a single bootstrap configuration wires substrate singletons, and task classes are added as category-keyed rule packs + named persona bundles rather than separate flow configs. The wired packs are (ADR-058):

• research (MVP supporting capability) — coordinator-routed prose research arc: plan → parallel gather fan-out → join → synthesize → review → artifact with recoverable sources.
• autoresearch (retained framework demonstration) — Karpathy-style propose/execute iteration loop with empirical keep/revert decisions and per-tenant devcontainer attestation (wired on disk with contract/integration coverage and opt-in browser journeys; outside the MVP claim and required demo-mvp / test:e2e gates).
• Parked donor material — the spec-authoring and software-implementation packs (create-change, proof-readiness, dev-from-task, dev-via-test) are unwired. SemDev currently implements that journey; its future absorption is separately qualified under ADR-061. The coordinator answers those asks honestly instead of routing them. See docs/demo-mvp-claims.md.

License

LICENSE.