Front Office

Design-ops system of record for projects built in conversation with AI: decision logs, open questions, and docs as generated views — so every session (human or AI, today or months from now, parallel or sequential) works from the same brain instead of chat scrollback.

Born from a real problem: designing a game across long AI sessions produced 46 logged decisions, and "was that ever actually approved?" kept needing an audit. Front Office makes the audit trail the primary artifact.

Core ideas

• The decision log is an event log. Every decision carries when / who / why, a provenance tag — [A] explicit human ruling · [A→C] human direction, AI spec · [C→A] AI proposal, human ratified · [C] AI-assumed, standing but vetoable — and a status (✅ decided · 🕐 doc-pending · 💬 proposed). Corrections are new entries referencing old ones, never edits.

• Open questions are records, not scrollback. Unanswered items live in a tracked file until resolved — with a log entry.

• Docs are builds. Context packs and status views are generated from the records; markdown is the storage and the interchange format, so there is no lock-in — the files are useful with no tooling at all.

• The rider guard. A proposal attached to an approved decision never inherits that approval. Drafts written by AI are always 💬.

Related MCP server: kb

Use

npm ci
npm run fo -- status                 # counts, unratified [C] list, pending rulings
npm run fo -- decisions --provenance C --status decided
npm run fo -- open --section A
npm run fo -- show 12
npm run fo -- pack                   # writes projects/<p>/context-pack.md
npm run fo -- validate               # CI-able: exit 1 on invariant violations

Project data lives in projects/<name>/ containing *decision-log.md and *open-items.md (see test/fixtures/ for the format). projects/ is gitignored — tenant data is yours and stays private. Point elsewhere with --project <dir> or FO_PROJECT_DIR.

Web UI

npm run fo -- pack   # optional: regenerate views first
npm run web          # http://localhost:4747 (FO_PORT / FO_PROJECT_DIR to override)

Live dashboard over the same files: decision feed with provenance/status chips and filters, attention strip (pending rulings, unratified [C]), open items by section, stats — and a draft form (drafts are always 💬). 100% UI/logic separation: the client contains zero business logic; every derived value arrives precomputed from /api/state, the browser only renders and sends commands.

MCP server (the brains hookup)

Expose the records to any Claude Code session:

claude mcp add front-office --scope user -- npx tsx <repo>/src/mcp/server.ts

Tools: get_context_pack · list_decisions · list_open_items · draft_decision (always 💬) · get_stats. Set FO_PROJECT_DIR in the server env to select the project.

Architecture

Per the project's own doctrine (yes, its design decisions are tracked in a Front Office log):

• src/core, src/adapters, src/views — pure (strict functional ESLint profile: no let/loops/classes/mutation, clocks and randomness must be injected).

• src/shell, src/mcp — the effects edge (moderate profile).

• Parsers keep raw cells verbatim → serialization round-trips exactly (parse(serialize(parse(x))) ≡ parse(x), property-tested).

npm run typecheck && npm run lint && npm test

MIT.