tecmie/harmony · scope and technical design

Harmony

A state engine for one person's software factory and knowledge. Two layers: a checklist of what needs attention, and the roots, signals and dimensions that knowledge is kept in. One Rust service, one Postgres. No Obsidian.

draft for approval · 2026-11-17 · rust, axum, sqlx, postgres · issue #1

Objective

One source of truth for what needs the owner, and one place the knowledge behind it lives, so nothing waits in a file for a human to notice it.

Agents and ingestion write what happened. Events create tasks. The owner has two verbs on a task, check and comment, from a phone or a laptop. The next session starts already knowing the answers. Decisions, fragments and notes stop being Markdown the owner maintains and become signals the system keeps.

Harmony does state. It stores prompts for the housekeeping a model has to do, and hands them to a runner; it does not reason on its own.

What it replaces

Today state lives in three places with three clocks, all Markdown in git repositories synced by timers: the war room table that exists only inside a Claude Code session; ~/.studio/<slug>/jira/STATE.md, backfilled by hand from merge history; and the Obsidian vault, which goes stale because the studio runs ahead of it. The rachis STATE.md is 801 KB, 97% a narrative log in five date styles. The vault holds 29 initiatives, 162 decisions, 68 fragments and 101 meeting notes that nothing reads back.

No product is this layer with the existing orchestrator as the writer. The control planes that come closest want to be the orchestrator, and two of them stopped in 2026. Harmony is a retrofit. Its knowledge model is not new either: rachis already implements signals, dimensions and initiatives. Harmony takes that model, drops the claim layer, and adds the checklist.

Two layers

LayerHoldsWritten byRead by
Attentiontasks and the owner's comments on themevents: agent closeouts, audits, merges, ingestion, housekeepingthe owner, on the PWA; every session, at start
Knowledgeinitiatives, roots, signals, dimensionsingestion, agents, housekeeping, the owner's rulingsagents, search, the owner when a task points there

A task is not a signal. A task says something needs doing or attention: a decision, feedback, a review, a clarification, or work in progress. A signal is a unit of knowledge. A task can point at a signal, a root, a branch or a pull request. The bridge runs one way: the owner's ruling on a task is recorded as a decision signal in the task's initiative.

The checklist

What the phone shows. Open tasks first, grouped by initiative, newest at the top. Each task expands to its comments. Check and comment are the only controls. Real tasks from the cloud.withrobin.ai review loop on 2026-10-29:

cloud.withrobin.ai · open
Which domain should account root emails use?asked by auditor:iam · points at audit of #54
decision
Add Config PutConfigurationRecorder and PutDeliveryChannel to protect-auditfrom the #50 audit · points at infra/landing-zone/src/scps.ts
feedback
Fix worker on feat/16-config-actionsunit in progress · executor started 16:40
progress
cloud.withrobin.ai · done
Should Co-authored-by: Cursor block a merge?asked by orchestrator · checked by drew 16:33
rulingYes, it blocks. Leave the three already on main alone; track new ones.
decision
Review the landing-zone audit before merging #50audit attached · checked by drew 16:24
review

Everything in the done group stays visible as a record of attention. Machine events that need no attention, a merge, a passing CI run, a closeout with no open risk, are not tasks; they are roots in the knowledge layer, and search finds them.

Task kinds

KindMeansCreated whenClosed by
decisionthe owner has to choosean agent raises a question; housekeeping proposes a dimension; ingestion finds a contradictiona comment of kind ruling, then check
feedbackan agent wants the owner's reactionan audit lists findings; a closeout flags a riskcheck, with or without a comment
reviewsomething is ready to be looked ata PR is ready; a generated document is readycheck
clarificationan earlier ruling is ambiguous in a new casean agent hits a case the ruling didn't covera comment of kind answer, then check
progresswork in flight, for visibilitythe orchestrator dispatches an executor or a session starts on a branchthe executor's closeout, automatically

Tables

tasks
  id            bigint       pk, monotonic
  initiative    text         fk initiatives.slug
  kind          text         decision | feedback | review | clarification | progress
  title         text         one line; what the list shows
  body          text  null   markdown detail
  ref_kind      text  null   root | signal | task | pr | branch | file
  ref           text  null   id, URL, branch name or path
  created_by    text         actor: drew, orchestrator, executor:<branch>, auditor:<persona>, housekeeping
  created_at    timestamptz
  done_at       timestamptz null   null means open
  done_by       text  null

comments
  id            bigint       pk
  task_id       bigint       fk tasks.id
  author        text         whose words these are
  via           text  null   who typed them, when not the author
  kind          text         ruling | answer | note
  body          text
  created_at    timestamptz

Knowledge: initiatives, roots, signals, dimensions

The vocabulary is rachis's, so the two systems can share prompts and later share a crate. The only departures: positions attach to signals rather than claims, and domains are gone because dimensions route directly.

Initiative

The only container. A client project, a product, a program, a personal pursuit are all initiatives. Merges the vault's initiative (entity, status, started) with rachis's (one-sentence scope, dimension weights).

initiatives
  slug          text   pk              "rachis", "cloud.withrobin.ai", "client-robin"
  name          text
  sentence      text                   what this initiative is, in one line
  entity        text                   personal | tecmie | wootiv | daccred
  client        text   null            set for client work
  status        text                   exploring | seeding | active | paused | completed | parked
  started       date
  studio_path   text   null            ~/.studio/<slug>, while the studio exists
  repo          text   null

Root

A source as it arrived: meeting notes, a brief, an email, a PDF, a closeout report, a merge. rachis calls these entries; in its edge ontology they are raw_source. Files live in Postgres.

roots
  id            bigint pk
  initiative    text   fk
  source_class  text           meeting | email | report | conversation | connector | database_export | wiki
                               | brief | closeout | audit | merge | ci | log
  title         text
  content       text   null    markdown or extracted text
  file          bytea  null    the original, when there is one; large objects above 32 MB
  file_name     text   null
  file_type     text   null    mime
  source_url    text   null
  created_by    text
  occurred_at   timestamptz    when it happened
  created_at    timestamptz    when it was recorded
  parent        bigint null    fk roots.id, for replies and attachments

Signal

A typed unit of knowledge extracted from a root, or recorded directly. A decision is a signal. The vault's fragment subtypes map onto these kinds one to one.

signals
  id            bigint pk
  initiative    text   fk
  root          bigint fk roots.id
  kind          text           fact | assumption | decision | idea | question | quote | action | reference | note
  name          text           the proposition, able to stand alone
  confidence    real   null
  lifecycle     text           active | quarantined | archived | deleted
  provenance    jsonb          span{start,end}, extractor, prompt_version, speaker, merged_from[]
  people        text[]
  search_vector tsvector       maintained by trigger
  embedding     vector(768)    null; Qwen3-Embedding; filled by a backfill job
  created_at    timestamptz

Dimension

An axis signals are positioned on. Not a topic: signals must be comparable on it. The contract is the paper's and rachis's, including its statuses and gates. Each initiative owns its dimensions; housekeeping proposes them and the owner validates them through a decision task.

dimensions
  id            bigint pk
  initiative    text   fk
  name          text
  definition    text           what low and high mean; what a signal must say to be positioned
  value_space   text           bounded_scalar | ordinal | categorical
  levels        text[] null    for ordinal and categorical
  prototypes    jsonb          2 to 5 example signals with their positions
  status        text           candidate | validated | provisional | active | parked | retired
  gates         jsonb          measurable, covered, distinct, non_redundant, stable: pass | fail | untested
  generator     text           admin | model_proposal | housekeeping | initiative
  version       int

signal_positions
  signal        bigint fk
  dimension     bigint fk
  version       int
  value         real           normalised to 0..1 for scalar and ordinal; category index otherwise
  relevance     real           how much this signal bears on the axis
  stale         bool           true after the dimension's definition changed
  pk (signal, dimension)

initiative_dimension_weights
  initiative    text   fk
  dimension     bigint fk
  weight        real
  pinned        bool

Positioning is done by a model reading text, not by embedding geometry: the prompt gets the dimension's definition and prototypes, the signal, and returns a value and a relevance. That is the cheap inference the design asks for. Ranking at search time uses rachis's term unchanged: relevance × (1 − distance) on each weighted dimension, added to the text score.

Prompts and housekeeping

Harmony holds the prompts for work that needs a model, and the log of each run. It does not run them. A runner asks for what is due, does it, and reports back.

prompts
  name          text   pk      extract_signals | position_signals | propose_dimensions
                               | gate_dimensions | fold_notes_into_decisions | tidy_tasks
  body          text           the prompt, versioned
  version       int
  schedule      text   null    cron expression; null means on demand
  scope         text           what the run may read: today_roots | initiative | all
  model_hint    text   null    cheap | smart

prompt_runs
  id            bigint pk
  prompt        text   fk
  runner        text           claude-code | studio-cli | openrouter
  started_at    timestamptz
  finished_at   timestamptz null
  summary       text   null
  tasks_created bigint[]       what it put on the checklist
RunnerHow it runsWhen
Claude Codethe /harmony:housekeep skill asks the MCP endpoint for due prompts, runs each with the model the session has, and reports through the same endpointon demand, from any session; the normal path
studio CLIthe CLI bundles the same skill and prompt client, so a cron on any machine can invoke studio housekeep through a local Claude Codescheduled, when a machine is on
OpenRouterthe service itself calls a model with an OpenRouter key, limited to scope = today_rootsnightly, unattended; optional, off unless the key is set

Anything a run wants to change that is not reversible, a new dimension, a merged signal, a retired one, becomes a decision task. Housekeeping proposes; the owner disposes.

Sequences of operation

An executor finishes a unit

  1. executorstudio root add --class closeout --initiative rachis --ref commit:a83f068 --file CLOSEOUT.md. The closeout is recorded as a root.
  2. executorFor each unresolved risk: studio task add decision --ref root:<id> --title "…". For the cleanup list: one feedback task.
  3. executorstudio task done <progress-task>. The unit leaves the open list.
  4. orchestratorSpawns the auditor. The audit arrives as a root of class audit and one feedback task with its findings.

The owner, on a phone, that evening

  1. ownerOpens the checklist. Two decisions, one feedback, one progress.
  2. ownerComments a ruling on the first decision and checks it. Harmony writes a decision signal in the initiative, root = the task.
  3. ownerChecks the feedback. Leaves the second decision open. That is a complete, valid state.

The next session starts

  1. hookSessionStart runs studio task list --open and studio comments --since <last session>. Both land in context before the first prompt.
  2. orchestratorReads the ruling, briefs the fix worker, adds a progress task for the fix branch with ref_kind = task pointing at the decision. The chain is in the refs.

A meeting is ingested

  1. owner or connectorstudio root add --class meeting --initiative client-robin --file notes.md, or a PDF. Stored with the file.
  2. runnerextract_signals is due for new roots. Each signal is written with its span; near-duplicates are quarantined.
  3. runnerposition_signals positions each new signal on the initiative's active dimensions.
  4. harmonyA signal of kind action with the owner as its person becomes a feedback task. A question addressed to the owner becomes a decision task. Everything else stays in the knowledge layer.

Nightly housekeeping

  1. runnerpropose_dimensions reads the day's new signals per initiative and proposes axes where signals cluster but no dimension covers them.
  2. runnergate_dimensions runs the five gates on candidates and marks each pass or fail.
  3. harmonyEach candidate that passes becomes a decision task: validate, park or retire. The owner rules from the phone.
  4. runnerfold_notes_into_decisions rewrites note signals that state a choice as decision signals, with the original kept in merged_from.

The owner pushes something from Claude on the phone

  1. owner"Add to rachis: the demo database on 3200 is read-only until Friday." Claude calls add_root with class conversation; extraction makes it a fact signal.
  2. owner"Check task 1343 and rule: withrobin.ai." Claude calls comment then check_task.
  3. owner"What did I decide about Cursor trailers?" Claude calls search; the decision signal comes back with its task and root.

Surfaces

One HTTP API inside the service, three fronts. None of the fronts can do anything the others cannot.

FrontWhoVerbsNeeds
studio CLIhooks, agents, cron, raydrtask add|list|done|comment · root add|get · signal list|search · dimension list · housekeep · initiative list|addthe service on loopback or LAN; a token in the CLI config
PWAthe ownerthe checklist: check, comment, read. Themes.the service public behind the wildcard-proxy Caddy, with a session cookie
remote MCP at /mcpthe owner, through Claude on the phone or Claude Desktoplist_tasks check_task comment add_root search due_prompts report_runthe same public endpoint, plus OAuth, the way the Robin connector works today

The CLI comes first: the SessionStart hook is a shell script and cannot call an MCP tool, and executors and auditors already live in Bash. The PWA and the MCP endpoint ship together because they share the one prerequisite, a public endpoint. Until then, Claude Code's Remote Control lets the phone drive a local session that has the CLI.

The PWA is a checklist and nothing more. No knowledge browsing, no graph, no editor. When a task points at a signal or a root, the PWA shows that one thing inline. Themes are a palette switch on the same page.

Search

Text first: BM25 over signal names and root content, with the dimension term added for initiatives that have active dimensions. The Qwen3-Embedding lane at 768 dimensions, served locally over loopback, is a config option that improves recall on paraphrase; it is off by default and never on the write path. Results fuse by reciprocal rank, as rachis does.

Workspace and deployment

One Cargo workspace, three crates, two binaries. One process and one Postgres in production.

CrateHolds
cognosthe types: tasks, comments, initiatives, roots, signals, dimensions, prompts; the HTTP client; the renderers. Shared by both binaries, so the CLI cannot drift from the API.
harmonythe service: axum + sqlx. Serves /api, /mcp, /healthz, and the PWA at / from assets embedded in the binary. Runs migrations, the quarantine check, the task-from-signal rule, the optional OpenRouter runner and the optional embedding backfill.
studiothe CLI. Talks HTTP to the service. Bundles the housekeeping skill. Installed with cargo install --path crates/studio; no network fetch at deploy time.

Migration

Two one-time imports, then the old stores are frozen. Nothing is deleted; replaced files are renamed with a prune_ prefix and listed.

FromBecomesCount
vault initiatives and client projectsinitiatives29 + 10
vault meetings, docs, inboxroots of class meeting, report, conversation101 + files
vault decisionsdecision signals, root = the meeting they cite where one exists162
vault fragments and atomssignals by subtype (insight → idea, signal → fact, log → note)68 + 173
studio STATE.md rowsroots of class log, verbatim, with occurred_at parsed1,341
studio owner questions and decisionstasks, done, with their rulings as comments33 rulings
cloud.withrobin.ai orchestration tablesroots and done tasks, account ids redacted164

Milestones

Ordered by dependency. Each is one issue. An auditor runs after 2, 3 and 5.

#DeliverableProven by
1Data model, this page, schema.sql and the fixturesthe owner approves; schema and fixtures are the first commit
2Checklist core: service, tasks and comments, the CLI task verbscargo clippy clean; tests; a task added by the CLI is listed, checked and commented by the CLI
3Hooks: SessionStart pull; closeout, audit and merge write roots and tasks; the Cursor-trailer rule lives as a rulingone real closeout runs through it and the next session starts with the open tasks in context
4Knowledge core: initiatives, roots with files, signals, text search; vault and studio importcounts match; 20 sampled decisions read correctly; a search for a known ruling returns it first
5PWA embedded in the binary, with themes; remote MCP; behind Caddy with auththe owner checks a task from a phone, and rules on one through Claude on the phone; both appear in the next session
6Prompts: the prompt tables, the /harmony:housekeep skill, extraction and positioning prompts, dimensions and gatesa meeting ingested at night produces signals, positions and at most a handful of decision tasks by morning
7Optional lanes: Qwen3-Embedding at 768-d over loopback; OpenRouter nightly runnerwith the network off, paraphrase search still works; with the key set, the nightly run reports without a session

Out of scope

Vocabulary, pinned

Three sources used the same words for different things. Harmony uses one meaning each.

WordIn HarmonyNot
taska checklist entry: something needs attentiona signal; a unit of work in a plan
signala typed unit of knowledge with a root and a spanthe vault's fragment subtype; a checklist item
notethe signal kind for an observation that is none of the othersthe vault's inbox capture; a page
decisiona signal kind, usually created by a rulinga page with its own template
roota source as it arrived, file includeda page; an entry's type
initiativethe only container; client projects includeda view over domains; a folder
dimensionan axis signals are positioned onan embedding size; a topic
statusone vocabulary per table: tasks open or done; signals by lifecycle; dimensions by the six statuses; initiatives by the vault's sixone shared enum
Sources. The survey of ~/.claudefiles, ~/.studio and ~/.local/vault on 2026-11-17; the phase 1 fixture (1,341 rows, 33 rulings); the survey of the geometric-knowledge evaluation plan, rachis's schema and dimension registry, and the vault templates; the market survey of 2026-11-17. The name Cognos replaces harmony-core for the shared crate.