tecmie/harmony · scope and technical design
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.
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.
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.
| Layer | Holds | Written by | Read by |
|---|---|---|---|
| Attention | tasks and the owner's comments on them | events: agent closeouts, audits, merges, ingestion, housekeeping | the owner, on the PWA; every session, at start |
| Knowledge | initiatives, roots, signals, dimensions | ingestion, agents, housekeeping, the owner's rulings | agents, 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.
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:
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.
| Kind | Means | Created when | Closed by |
|---|---|---|---|
decision | the owner has to choose | an agent raises a question; housekeeping proposes a dimension; ingestion finds a contradiction | a comment of kind ruling, then check |
feedback | an agent wants the owner's reaction | an audit lists findings; a closeout flags a risk | check, with or without a comment |
review | something is ready to be looked at | a PR is ready; a generated document is ready | check |
clarification | an earlier ruling is ambiguous in a new case | an agent hits a case the ruling didn't cover | a comment of kind answer, then check |
progress | work in flight, for visibility | the orchestrator dispatches an executor or a session starts on a branch | the executor's closeout, automatically |
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
decision task cannot be checked without a ruling. The ruling is written as a decision signal in the initiative, with the task as its root.progress task is closed by the machine when the closeout arrives; the owner can also check it.feedback task with four lines, not four tasks, unless the auditor says they need separate rulings.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.
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
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
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
merged_from.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.
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
| Runner | How it runs | When |
|---|---|---|
| Claude Code | the /harmony:housekeep skill asks the MCP endpoint for due prompts, runs each with the model the session has, and reports through the same endpoint | on demand, from any session; the normal path |
studio CLI | the CLI bundles the same skill and prompt client, so a cron on any machine can invoke studio housekeep through a local Claude Code | scheduled, when a machine is on |
| OpenRouter | the service itself calls a model with an OpenRouter key, limited to scope = today_roots | nightly, 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.
studio root add --class closeout --initiative rachis --ref commit:a83f068 --file CLOSEOUT.md. The closeout is recorded as a root.studio task add decision --ref root:<id> --title "…". For the cleanup list: one feedback task.studio task done <progress-task>. The unit leaves the open list.audit and one feedback task with its findings.decision signal in the initiative, root = the task.studio task list --open and studio comments --since <last session>. Both land in context before the first prompt.progress task for the fix branch with ref_kind = task pointing at the decision. The chain is in the refs.studio root add --class meeting --initiative client-robin --file notes.md, or a PDF. Stored with the file.extract_signals is due for new roots. Each signal is written with its span; near-duplicates are quarantined.position_signals positions each new signal on the initiative's active dimensions.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.propose_dimensions reads the day's new signals per initiative and proposes axes where signals cluster but no dimension covers them.gate_dimensions runs the five gates on candidates and marks each pass or fail.decision task: validate, park or retire. The owner rules from the phone.fold_notes_into_decisions rewrites note signals that state a choice as decision signals, with the original kept in merged_from.add_root with class conversation; extraction makes it a fact signal.comment then check_task.search; the decision signal comes back with its task and root.One HTTP API inside the service, three fronts. None of the fronts can do anything the others cannot.
| Front | Who | Verbs | Needs |
|---|---|---|---|
studio CLI | hooks, agents, cron, raydr | task add|list|done|comment · root add|get · signal list|search · dimension list · housekeep · initiative list|add | the service on loopback or LAN; a token in the CLI config |
| PWA | the owner | the checklist: check, comment, read. Themes. | the service public behind the wildcard-proxy Caddy, with a session cookie |
remote MCP at /mcp | the owner, through Claude on the phone or Claude Desktop | list_tasks check_task comment add_root search due_prompts report_run | the 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.
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.
One Cargo workspace, three crates, two binaries. One process and one Postgres in production.
| Crate | Holds |
|---|---|
cognos | the 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. |
harmony | the 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. |
studio | the CLI. Talks HTTP to the service. Bundles the housekeeping skill. Installed with cargo install --path crates/studio; no network fetch at deploy time. |
pgvector installed but unused until the vector lane is switched on. Files as bytea up to 32 MB, large objects above.pg_dump to the same place. Harmony is the record; this is the one thing that must not be lost.Two one-time imports, then the old stores are frozen. Nothing is deleted; replaced files are renamed with a prune_ prefix and listed.
| From | Becomes | Count |
|---|---|---|
| vault initiatives and client projects | initiatives | 29 + 10 |
| vault meetings, docs, inbox | roots of class meeting, report, conversation | 101 + files |
| vault decisions | decision signals, root = the meeting they cite where one exists | 162 |
| vault fragments and atoms | signals by subtype (insight → idea, signal → fact, log → note) | 68 + 173 |
studio STATE.md rows | roots of class log, verbatim, with occurred_at parsed | 1,341 |
| studio owner questions and decisions | tasks, done, with their rulings as comments | 33 rulings |
| cloud.withrobin.ai orchestration tables | roots and done tasks, account ids redacted | 164 |
log roots; only new events are typed. A regex pass on the old rows was wrong about 30% of the time.Ordered by dependency. Each is one issue. An auditor runs after 2, 3 and 5.
| # | Deliverable | Proven by |
|---|---|---|
| 1 | Data model, this page, schema.sql and the fixtures | the owner approves; schema and fixtures are the first commit |
| 2 | Checklist core: service, tasks and comments, the CLI task verbs | cargo clippy clean; tests; a task added by the CLI is listed, checked and commented by the CLI |
| 3 | Hooks: SessionStart pull; closeout, audit and merge write roots and tasks; the Cursor-trailer rule lives as a ruling | one real closeout runs through it and the next session starts with the open tasks in context |
| 4 | Knowledge core: initiatives, roots with files, signals, text search; vault and studio import | counts match; 20 sampled decisions read correctly; a search for a known ruling returns it first |
| 5 | PWA embedded in the binary, with themes; remote MCP; behind Caddy with auth | the owner checks a task from a phone, and rules on one through Claude on the phone; both appear in the next session |
| 6 | Prompts: the prompt tables, the /harmony:housekeep skill, extraction and positioning prompts, dimensions and gates | a meeting ingested at night produces signals, positions and at most a handful of decision tasks by morning |
| 7 | Optional lanes: Qwen3-Embedding at 768-d over loopback; OpenRouter nightly runner | with the network off, paraphrase search still works; with the key set, the nightly run reports without a session |
Three sources used the same words for different things. Harmony uses one meaning each.
| Word | In Harmony | Not |
|---|---|---|
| task | a checklist entry: something needs attention | a signal; a unit of work in a plan |
| signal | a typed unit of knowledge with a root and a span | the vault's fragment subtype; a checklist item |
| note | the signal kind for an observation that is none of the others | the vault's inbox capture; a page |
| decision | a signal kind, usually created by a ruling | a page with its own template |
| root | a source as it arrived, file included | a page; an entry's type |
| initiative | the only container; client projects included | a view over domains; a folder |
| dimension | an axis signals are positioned on | an embedding size; a topic |
| status | one vocabulary per table: tasks open or done; signals by lifecycle; dimensions by the six statuses; initiatives by the vault's six | one shared enum |
~/.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.