Each product Startup OS operates has an Operations Instance: a repository named operations in the product’s own GitHub organization. Your product’s code stays in its own repository. The Instance holds everything else: what the business is, what is true right now, where it is going, what Startup OS may do, and a record of everything it has done.
Startup OS owns the shape of the repository. You own what is in it.
At a glance
| Path | Holds | Written by |
|---|---|---|
STARTUP-OS.yaml |
The manifest: identity, stage, repositories, permissions, governance | Onboarding, then you |
PRODUCT.md |
What the business is | You. A change is a strategic decision. |
CONTEXT.md |
What is true right now | Startup OS and you |
context/ |
Objective, bets, metrics, open questions, and more | Split between you and the loop |
config/ |
Schedule, loop steps, channels, evidence sources | Onboarding, then you |
runs/ |
One folder per run, one file per step | The loop |
execution/log.jsonl |
Every action Startup OS took | The loop, append-only |
observations/ |
Evidence, one file per day, never revised | The loop |
docs/ |
Plans, reviews, specs, experiments, decisions | You and Startup OS |
templates/ |
Blank artifacts to start from | Startup OS |
routines/ |
Tasks that run on your machine, for products that publish locally | Startup OS |
STATUS.json |
The summary the dashboard reads | The loop |
The manifest
STARTUP-OS.yaml is the source of truth for how Startup OS may treat the product. The GitHub App reads it from the default branch only, so a proposed change has no effect until it is merged.
| Section | What it declares |
|---|---|
metadata |
The product’s id, name, and organization |
spec.stage |
pre-revenue, finding-fit, scaling, mature, winding-down, or unknown until you answer |
spec.context |
Where PRODUCT.md and CONTEXT.md live, and where agent instructions live in the product’s repository |
spec.repositories |
The Instance and the product’s own repository. Startup OS acts on nothing outside this list. |
spec.governance |
The autonomy level, guardrails, the escalation channel, and the per-run model budget |
spec.capabilities |
What Startup OS may do. See Permissions and operating modes. |
spec.metrics |
Metric definitions. Empty until you define one. |
spec.cadences |
Whether daily, weekly, and quarterly cadences are on |
spec.skills |
Which skills the product may use |
spec.startupOS |
The platform versions this Instance is compatible with |
Context
PRODUCT.md says what the business is: the problem as the customer states it, who it is for, what it replaces, how it makes money, and what you have decided not to do. It changes rarely, and a change is a strategic decision.
CONTEXT.md says what is true right now. Every metric in it carries a source and a date. Startup OS updates it freely, because recording what it observed is not deciding anything, and treats it as unverified once it is more than seven days old.
The context/ folder breaks that picture into notes. Three are yours alone, and the loop reads them but never writes them:
| File | Holds |
|---|---|
context/direction.md |
Your strategic objective and the stop conditions that override everything else |
context/map.md |
The product’s repositories and who owns what |
context/voice.md |
What the product may claim, and how it speaks |
The other seven are the loop’s working notes: metrics.md, bets.md, problems.md, questions.md, actions.md, in-flight.md, and changes.md. The loop never edits them directly. It proposes each edit as a pull request in the Instance, which you merge.
Configuration
| File | Controls |
|---|---|
config/schedule.json |
When each scheduled turn runs, and whether it is on |
config/loop-steps.json |
The loop’s steps: inputs, outputs, and what the act step may touch |
config/evidence-sources.json |
Connected data sources, such as billing and analytics. Starts empty. |
config/social.json |
Social channels and communities. Delete it if the product does not publish socially. |
config/commitments.json |
Where dated commitments live, so none is forgotten |
config/development.json |
Limits on code changes. Ships closed. |
config/template-version.json |
The platform release the Instance was built from, with a checksum for every generated file |
You can edit the schedule and most settings from the dashboard’s configuration page. Every change arrives as a pull request.
Run history
The loop keeps a record you can audit without asking anyone:
runs/<run-key>/holds one file per step. The run key is the product and the ISO week, so a retried step overwrites its own file rather than adding a second one.execution/log.jsonllists every action Startup OS proposed or took, one line each, and is never rewritten.observations/holds the evidence each run started from, one file per day.
Your product’s repository
The Instance never writes to your product’s repository directly. Issues the loop files, and alerts about its own health, are filed there. Instructions for agents working on the code live at its root in AGENTS.md. The loop itself does not check your code out.
Staying current
The generated files in an Instance, such as workflows and routines, belong to the platform and move with its releases. config/template-version.json records exactly which release each came from.
When the platform releases, it opens an adoption pull request in every registered Instance. It never merges one. You merge it on GitHub, or with Update on the product’s dashboard page, which merges as you, using your own GitHub account. You can also run sos adopt yourself. An adoption replaces only the generated files and reports new configuration keys rather than merging them into yours.
Edit a generated file by hand and the Instance’s own validation fails, because the checksum no longer matches. Keep changes in the files that are yours.
GTM business records
An adopted product retains thesis snapshots in docs/gtm/, tests in its manifest-declared experiment directory, approved plans and accepted decisions alongside existing evidence and reviews. Links pin the exact source versions. Templates and proposed plans are candidates; current accepted records govern later work. Failed tests and old strategies stay in history. These product-owned records are preserved by platform adoption. See Go-to-market workflow.