What Syns is, why it exists, and what we hold to be true.

This guidebook says what Syns is and why.

The parts

• I · Why we exist — the beliefs, and the ambition they force.
• II · The ladder — why markdown, why sharing, why a product. Three steps; each depends on the one before.
• III · The problem — what goes wrong for teams whose agents write the reasoning.
• IV · The answer — what Syns is, in layers, and what we refuse to build.
• V · The objections — why nobody built it, why the alternatives fall short, who the neighbours are.
• VI · Who it is for — the profile, the buyer, and who we turn away.
• VII · Come back here — one-screen reference cards. Open these mid-conversation.
• Glossary — every term we use, one line each. Dotted underlines in the text jump here.

Syns rests on four statements about where software development is going. None has a date. The argument depends on the direction, not the pace.

The flip

Today code is the asset. We read it, review it, maintain it, and fear breaking it.

When agents write the code, the asset flips.

Code becomes disposable. The specification becomes the durable artifact.

The asymmetry is exact. From a good specification you can rebuild the software. From the software you cannot rebuild the specification.

Code holds a decision's consequence. It never holds the decision.

Where this leads → 3 · The ambition. The beliefs as a list → 22 · The beliefs.

Building does not go away. It moves.

A good specification removes ambiguity about what the software should do.

A good process turns that specification into working software reliably.

With both in place, the code is no longer something to audit. We trust the result because we trust the process that produced it.

Because the process is reproducible, we can generate the software again and get the same outcome.

Code quality becomes a consequence, not a concern.

What the builder now does

• Writes and maintains the specification — the boundaries, the trade-offs accepted, the things deliberately not built.
• Designs the workflow the agents follow.
• Builds the evaluations that prove the process works.
• Reads the reasoning, not the diff.

The work ahead is not making agents smarter. It is building the specifications, the workflows, the evaluation systems and the interfaces that make this real inside engineering teams.

That is the work Syns is for.

Why the spec has to be written at all → 9 · Why write it down.

Syns is the product form of the beliefs in chapter 1.

Syns hosts the reasoning that produces code. GitHub hosts the code.

The reasoning is the deliberate artifacts: plans, specifications, architecture decisions, configurations, the files that guide an agent to build software.

Syns does not host code. It does not train or tune models. It builds the engineering layer around them: storage, versioning, access control, coordination, discovery.

Every belief maps to a design choice

Without the beliefs, Syns makes no sense

• If code is the asset, GitHub is enough.
• If reproducibility does not matter, versioning specifications is pointless.
• If models alone will solve it, no infrastructure is needed.
• If humans still write most software, coordination for many parallel agents is overbuilt.

Hold the beliefs fully, and something like Syns is inevitable. The beliefs are the thesis. Syns is the product.

The short form → 21 · Syns in one breath.

Markdown is the native input and output of every coding agent.

An agent works by reading files, writing files and running commands. Its skills, its memory, its plans and its instruction files are already markdown. Working in markdown asks it to learn nothing and install nothing.

Cloud agents do not change this

Belief 2 moves the agent off your laptop into a sandbox. A sandbox has a filesystem and a shell. A cloud agent reads and writes a markdown file exactly as a local one does.

What disappears when agents leave the laptop is the shared disk. That is what makes the next rung mandatory rather than convenient.

The case, strongest first

1. Zero integration. A database, a document platform or a vector store needs a tool call, a schema, and a decision about when to write. A file appears as a side effect of working.
2. No schema in advance. The shape of agent reasoning is not known up front. The sections, the wording and the layout of the folder emerge from the work. Text holds a thought that has no field yet; structure is added only where it has emerged.
3. Human-inspectable, and a change is readable. The person holding the intent must be able to read and correct it. A changed sentence is readable in any editor. A restructured JSON blob or a database row is not.
4. Cheaper than a document platform. Reading a Google Doc or a Notion page through its API costs a lossy round-trip on every access. A folder of markdown is the cheapest thing an agent can work on.
5. It survives us. A folder of markdown outlives the product, the vendor and the format decision. Leaving Syns costs one download. That is what makes trusting a hosted service safe.

Next rung → 5 · Why sharing. The alternatives to files → 16 · Why not X.

Human teams shared knowledge beside the code for decades: a Slack message, a standup, a comment on the Linear ticket.

Those channels were built for a human reader. The reader is now an agent.

An agent starting a task does not read yesterday's Slack thread, was not in the standup, and does not open the ticket unless told to. What it reads is the files in its working directory.

What has to be shared is the markdown itself, as files an agent will load — not a summary a human types into a chat.

Under belief 2 this stops being a preference

Two agents in two sandboxes have no shared disk.

Either a layer built for it synchronises the reasoning between them, or each works from whatever happened to be in its sandbox when it started.

Next rung → 6 · Why a product. The problem this produces → 7 · Nowhere to live.

This is the question everyone asks: why not GitHub? The answer has two steps.

Step one — the reasoning gets its own repository

Agents iterate on the reasoning far more often than on the code. A plan is rewritten twenty times while the code it describes changes once.

Kept in the code repository, that rate of change has two bad outcomes and no good one:

• Commit every turn, and the code's history is mostly agent text.
• Commit once, and the progression that made the document worth keeping is thrown away.

There is no right commit granularity for a document a machine is thinking through. Commit granularity is a human editorial decision, and there is no editor.

Some agents produce no code at all. An agent using markdown as memory has nothing to commit alongside.

The reasoning also has a different shape from code, and the difference shows in four places:

• Non-developers work in it. A change in business strategy reorganises the backlog and rewrites what will be delivered. Product, design and management people make that change. The codebase is untouched while it happens.
• It is true regardless of branch. A decision holds whichever branch of the code you have checked out. A file that lives inside a branch cannot say that.
• It spans repositories. Requirements and decisions live outside any single code repository. One project can reference the decisions and context of another. Specs, changes and planning context are separable from the code they describe.
• It moves faster than the code. Ideas are explored and iterated in the reasoning long before — and often without — a codebase update.

So the reasoning goes in a repository of its own, or it damages the one it lives in.

Step two — that repository does not belong on a code host

Once the reasoning is separate, a code host is a general-purpose remote holding an artifact it was not built for.

• Many agents write it in parallel, on many machines and in many sandboxes, and every one has to be current without anyone running a step.
• Changes arrive continuously and in small pieces. No human decides when a thought is finished, so there is no commit to make. What you want to inspect is not a flat list of commits but what an agent was working on, what context it held, and how its change affected the other documents.
• Nothing in a code host reads the text for whether it still means what it meant.

What works for code — branches, pull requests, review, a human at the keyboard — does not work for files updated continuously by machines and consumed by machines.

What a purpose-built host does instead

• Keeps every copy current across every agent, with no ceremony to set up.
• When one agent changes a file while another is working on it, reconciles both changes against the live shared state. Nobody's work is overwritten.
• Says things about the whole set of documents a code host has no reason to say: which concepts are duplicated, which statements disagree, what the agents actually read.

Where a team already keeps a separate planning repository, the argument is never against their structure. It is that the remote underneath it can do more.

The full head-to-head, including GitHub → 16 · Why not X. Why nobody built this → 15.

Every agent session produces two artifacts: the code, and the reasoning behind it. Only the code has a home.

The code goes to the code repository. The reasoning — the plan, the decisions, the alternatives rejected, the retrospective — sits in a local folder on whichever machine produced it.

A second agent on a second machine does not know it exists.

What that costs

• A teammate's agent rebuilds a plan that already exists.
• An agent contradicts a decision it never saw, correctly, given what it read.
• With N agents, the pairs that can collide grow as N². None of them builds any memory of who works on what.
• The team lead who wants to know what the agents decided has to ask around, or go looking.

Agents work blind. No agent knows what any other is planning or doing.

The channels a team already has — chat, a ticket, a call — carry knowledge between humans. An agent starting a task reads none of them.

This is the reason a team goes looking for somewhere to put the reasoning. It is what Syns solves first.

The second problem, which arrives once this one is solved → 8 · Intent drift.

Your intent is what you want the system to do and how you want it built: which module owns what, which trade-off you accepted and why, which feature you decided not to build.

Code cannot hold it. So the intent lives in documents, and the agents read them before they build.

Intent drift is when a document stops matching what you meant, and nothing tells you.

An agent finishes a task and updates the document to describe what it did.

The new sentence disagrees with a paragraph it never opened.

Nothing breaks. The code compiles. The tests pass.

The next agent reads the drifted document, treats it as the specification, and builds on it.

The system bends away from what you wanted while every check stays green.

Two properties make it expensive

• It is invisible to every check you already have. Compiler, tests, CI, code review — all pass. The only detector is a person who remembers what they meant, and the only evidence is the text.
• It compounds. Each drifted document is the input to the next agent run. Later work amplifies the error instead of correcting it.

Three ways a document decays

Why the human fix stops working

The workaround is to re-read the documents after every change and correct them. That loop is right, but it has three problems.

1. Reading costs time the team eventually stops paying.
2. A drifted sentence reads perfectly well, so people skim past it.
3. A correct fix in one file silently invalidates a statement in another.

The third problem ends the loop. Nobody decides to stop reviewing. The cost exceeds the perceived benefit, and after that drift is unbounded.

This is the reason a team that already shares its reasoning keeps paying.

The layer that catches it → 11 · Three layers. Why a spec at all, given this → 9.

A specification is a second thing to maintain, and it can disagree with the code. That disagreement is exactly the failure chapter 8 describes. So: no spec, no drift. Why not let agents work from the code plus the conversation?

Four reasons the objection fails

• Code cannot hold the decision. You can read what the system does. You cannot read the trade-off that was accepted, or the alternative that was rejected.
• Negative space cannot be written in code. "We deliberately did not build X" has no expression in a codebase. The absence looks identical to an oversight, and an agent will helpfully add X back.
• The specification has a different shape from the code. It holds business context, priorities and plans that change without the code changing, and that non-developers own. Code has nowhere to put them — see chapter 6.
• Inference is neither free nor stable. Working intent out from the code costs context on every run, and produces a slightly different answer each time. Writing it once and reading it is cheaper and deterministic.
• Drift is a detectable failure. Absent intent is an undetectable one. A spec that disagrees with the code can be found and fixed. Intent that was never written down cannot be checked against anything.

Where the objection wins

One person, one agent, one short-lived project. The intent fits in a head and a context window, and a specification is overhead.

That case is real. It is not who we build for — see 18 · The profile.

A repository in Syns is a versioned collection of the markdown files that tell agents what to build.

Specifications, plans, architecture decisions, configurations, instruction files, retrospectives.

Not source code — that stays where it is. Not transcripts or prompts — those are how an agent got somewhere, not what it decided.

Everything in a Syns repository got there because someone or something decided to write it down.

That one sentence separates Syns from every memory database and every session recorder. We store deliberate artifacts, not inferred state.

The loop

Each step, one line

1. Set up. A person points an agent at the setup skill. It reads the codebase and whatever markdown already exists, asks what it cannot infer, and proposes a structured wiki. It ends with a review page showing every source, the existing markdown, the proposed structure, and which fact came from where. Nothing is invented, the old structure is backed up, and everything is revertible.
2. Sync. Every agent session updates from the shared state before its first turn and sends its changes at the end of each. The wiki is current on every machine and in every sandbox without anyone running a step. Nothing sits inside the agent's reasoning loop.
3. Work. People and agents store, read, review and collaborate on the markdown.
4. Health. Syns scores the wiki from two independent sources: structure checks (frontmatter valid, links resolve, dates fresh) and each agent's behaviour against its own baseline (a session that normally makes three edits making fourteen). Either alone is gameable.
5. Repair. A separate agent fixes the structure so the problem does not come back. It never reverts — it fixes on top. It has to be separate because the agent that went wrong does not know it did, and cannot read across sessions.

How it works underneath, one line each

• An update is one unit. A set of changed files becomes exactly one new version. There is no half-applied state.
• Only what changed travels. Unchanged files are sent as fingerprints. A large repository with one changed file costs a kilobyte on the wire.
• Reconciled changes. When another agent changed a file while you were working, your update is reconciled against the live shared state. No one's work is overwritten and no conflict files appear.
• Full history — per repository, per file, per agent, per turn — with revert to any point.
• Teams and roles. A private repository is indistinguishable from a non-existent one to anyone without access.
• Every action is recorded from the first day. Deleting a repository does not delete the record of what happened to it.
• Tool-agnostic. It does not care which agent or methodology wrote the file, and it sits underneath the workflow tools, not in front of them.

The principles as a list → 23 · The principles.

The answer to Part III is three layers. The order is load-bearing: the third exists only on top of the first two. That is the whole reason a purpose-built product can exist here.

L1 makes drift detectable in principle. L2 makes it a team's problem rather than one person's — and creates the drift that matters most, between agents that never meet. L3 is the only part a customer cannot assemble themselves.

The full sentence, worth knowing by heart:

Agent-produced markdown cannot be shared by the tools built for humans, and once shared it drifts from the builder's intent, silently and cumulatively. The only place either can be fixed is a persistent, shared, versioned record of what every agent read and wrote. Syns is that record, and the instruments over it.

One L3 concept worth knowing → invariants. What only we can hold → 13.

Keep this list separate from the next chapter. This is what a team feels. Chapter 13 is what a competitor cannot copy. They are different lists.

Where value lands first

Setup and sharing — not health, not repair.

The sequence a team feels: a structure that fits gets set up, a second person joins, their agents work in it together, task time and token spend drop.

The failure it is measured against: one shared markdown file, each agent on a different page, ageing files, and chat as the archive.

L3 is what makes the value permanent, not what makes it start.

Reviewing code scales with agent throughput, which only goes up. Reviewing intent scales with the size of the documents, which is bounded and can shrink.

That asymmetry is the answer to anyone who says review is already their bottleneck.

Individually weak, jointly hard to copy. This order is not the order that shows best in a room.

1. The vendor-neutral, tool-agnostic position. Every new workflow tool expands the value. Workflow tools have a structural reason not to be cross-tool. The heaviest agent users mix vendors deliberately and will not keep their decision layer with one of the parties they want to switch between.
2. The read⋈version join. Which agent read which lines, when, against what the file said at that moment. Harness vendors see reads for their own agent only. Observability tools see reads without file versions. The join exists nowhere else, and only a layer that does both the sync and the hooks can hold it. Every L3 instrument is made of it.
3. The template library. Proven structures, tagged and carrying usage knowledge. Every wiki set up teaches the next proposal.
4. Accumulated versioned team knowledge, and eventually a public library with forking and attribution. A network effect; not load-bearing yet.
5. Sync itself — multi-agent coordination and the managed infrastructure under it. The demo, not the advantage that lasts.

What we deliberately do not try to own

Contradiction detection, duplication detection, over- and under-specification checks, the removal check.

These run as verification steps inside the templates, on the customer's own model, client-side. Syns interprets and visualises their output.

Three consequences, all intended: the cost sits visibly on the customer's side; further commoditisation costs us nothing; and the market improving these checks improves Syns for free.

They are on the advantage list in chapter 12 and off this one. That is the most consequential product decision we have made.

Lead demos with sync. Build the business on the first three.

The thing that shows best is last on the list. The thing worth most is hardest to show.

Why not the tracker, at length → 16 · Why not X.

Why hasn't GitHub, Cursor, or a frontier lab shipped this?

They have — each vendor, for its own agent.

A harness vendor attaches a session link to every commit. An editor company replaces git for its own editor. A code host renders the markdown its own agent produces.

Each one is single-vendor, and each one stores what its own agent did.

The gap that leaves

• A team running two harnesses side by side is served by neither.
• The heaviest agent spenders mix vendors on purpose, to keep the option of switching. They will not store their decision layer with one of the parties they want to switch between.
• A vendor billing per token has no interest in a layer whose job is to reduce reads.
• Platforms ship the single-player version that covers most of their own users. The neutral specialist wins the category.

The honest risk

The residual risk is not that a platform builds the feature. It is that a platform acquires the neutral player. Say that plainly when asked; dodging it costs more than naming it.

Where the vendor moves are tracked → 17 · The neighbours.

Two tests. The first asks whether a channel can move the artifacts at all. Several alternatives pass most of it. The second asks whether it can tell you the artifacts went wrong. Nothing on the list passes that.

Test 1 — can it move the artifacts?

Test 2 — can it tell you the artifacts went wrong?

Nothing in either test is exotic. The alternatives fail on ordinary criteria.

The alternatives

The grid

No alternative is bad at everything. The issue graph clears test 1 outright; the disagreement with it is about the format. What separates the list is test 2 — the columns that are the argument.

The tracker question, at length

Linear, Jira and GitHub Issues already hold requests, detail and reports. Keep them.

• Replacing a tracker is a different and much harder business. Nothing in the wedge requires winning that fight.
• A ticket is a unit of coordination between humans: owner, state, priority. A spec is a unit of context for an agent: content, structure, version.
• Because writing a file is free, a team writes six artifacts per unit of work — spec, plan, decisions, review, verification, retrospective. Nobody writes six tickets.

The counter to have ready: tracker documents are markdown too and agents can write them by API. The API path is a separate act of publishing to a remote system — exactly the step that gets skipped.

The short answers for a conversation → 27 · When someone asks.

The category is called spec-driven development, or context engineering, depending on who is talking. All of it produces markdown as the durable artifact of agent reasoning.

The workflow tools are complements

A dozen tools — from a solo maintainer's viral repository to first-party offerings from Microsoft, Amazon and Google — do a variant of the same five steps:

1. Intercept the user's request to a coding agent.
2. Force a structured workflow: clarify → spec → plan → implement → review.
3. Produce markdown artifacts.
4. Store them locally, in a tool-named folder — openspec/, .specify/, .planning/, conductor/.
5. Drop the user back into the agent to run the plan.

Because step 4 is always local and always theirs, none of them sync across machines, keep history beyond local git, share a set with attribution, coordinate several agents on one set, or say anything about whether the markdown is still true.

They produce the artifacts. Nothing in the list stores, coordinates or analyses them. Each one that says "the store is just a git repo" is a socket, not a competitor.

Five families that share the premise and differ on the object

Two more shapes

• Execution platforms that carry context as a line item. A factory-model product takes tickets to PRs on its own infrastructure and includes a memory layer on the menu. Nobody has to decide to compete with us; a bundled line item removes the reason to buy a dedicated layer.
• Vendor-native provenance. A harness vendor attaches a session link to every commit by default. One session, one vendor, read-only, nothing synced or reused. The first sign of an incumbent moving toward the provenance end.

What would change our plans

• A workflow tool ships its own hosted sync.
• A code host or a cloud platform ships a hosted spec service.
• An agent-native VCS adds markdown-aware analysis or a shared hosted set of documents.
• A plan workspace adds consistency checking across all its plans.
• A retrieval-first knowledge base preserves the authored files, or joins reads to versions.
• The schema bet wins — teams accept that intent belongs in a schema. This is a premise risk, not a competitive one.

A tripwire fires an investigation, not a conclusion. A move that looked like a threat on a README paragraph has turned out to be an integration opening on the documentation.

The bets as a list → 24 · The bets.

Team size predicts the pain badly. Three other things predict it well.

Why this profile, and not the solo developer

A solo developer with one agent holds the intent in their head and notices when a document stops matching it.

That stops being possible when work spreads across dispatchers, agents and sandboxes. Nobody holds the whole intent. Nobody sees the whole record. Drift compounds where no one is looking.

A solo developer running several agents is the doorway — fastest in, easiest to convert. The network effect starts at the second dispatcher, and so does the paid tier.

Two people who disprove headcount as the predictor

• A disciplined solo developer with a private repository feels nothing.
• An architect who serialises every agent run through file locking sees zero conflicts.

Both removed coupling, not agents.

The qualifying signal

They describe a coordination or consistency failure in their own words before we mention one.

"My agents keep undoing each other." "The plan file said one thing and the code did another."

Someone who says this has the problem and does not need convincing it exists. Its absence across a run of conversations is the cleanest sign the profile is drawn wrong.

The secondary profile

Individual developers using a workflow tool, whose agent markdown lives in a local repository and renders badly on a code host. Lower urgency, much larger, and a hundred substitutes — every editor, every notes app, the code host itself. Drift affects them too; they feel it later and blame something else. Layer in after the primary profile has traction.

The profile on one card → 26 · Who we target.

• The budget holder is the CTO or VP Engineering. The adoption lead champions. Under about twenty engineers both collapse into the founder, which is why small teams close faster.
• Individual developers feel the pain, and cannot fix it alone. Drift and blind agents are a property of the whole team's documents. One developer fixing their corner changes nothing. So the decision is a team decision, and the bill lands with the budget holder.
• Adoption fails on workflow change, not on value. The buyer's condition: integrated, non-invasive, no learning curve. "You install it, it runs in the background, you roll it in slowly." A pitch that implies changing how the team works loses at this step regardless of argument.
• The buying frame is velocity. Decision makers judge agent tooling by whether they can still change the codebase as fast at month six as at week one. Not by contradiction counts, health scores or token spend.
• Willingness to pay is shaped per seat, conditional on the workflow not changing.

Two motions, and a third that is not a sale

Two things never to open with

• Cost or tokens. Capacity-constrained teams feel it. Small or funded teams explicitly do not — one CTO: every developer already has the subscription. Leading with cost to the wrong half is falsifiable in the room.
• Conflict prevention. Competent teams solve conflict by scoping work up front, and say so. Conflict is a supporting claim. The knowledge argument — what survives for whoever returns to the system in three months — is the durable one.

• People who want a hosted alternative for source code. That is GitHub.
• People who want a real-time collaborative editor. Permanent, not staged. Someone who wants a cursor next to a colleague's is a disqualification, not a "later".
• People who want a prompt marketplace.
• Teams running one agent, with no markdown workflow and no second dispatcher. Not to be confused with the team that documents nothing — that team is agent-heavy and primary.
• Companies whose security review blocks a non-enterprise hosted product. Deferred to a tier that does not exist.
• Large organisations with rigid workflows and long procurement, even where the pain is real and even where they engage. Engagement is not qualification.
• Non-technical teams, for now. The product works for them — a person with an agent and a markdown editor gets the same sync and history. It is true of the product, not who we target, and not something we claim until a reference exists.