How SiftOS works.
Four phases, twelve commands, one ledger. Every product decision becomes a dated entry with a prediction and a metric — and the outcome posts later, next to the prediction that made it.
Shape it consciously
What are we deciding, what are the options, and who owns the call?
Name the metric
Write the expected outcome and the metric that will judge it — before building.
Post the result
When results land, the outcome posts with the measured delta — next to the prediction.
Close the loop
What did we get right, and what changes in how this team decides?
Start — build context
SiftOS begins with the memory: what this product is, who it serves, and how it will know it is working.
siftos initsiftos shapeinit builds persistent product context progressively —PRODUCT.md, STRATEGY.md, METRICS.md,PRINCIPLES.md, ROADMAP.md. It never ships placeholders as truth: siftos doctor reports memory that is still empty.
shape turns an idea into a Bet — problem, target user, hypothesis, success threshold (SVT), scope, non-goals, and measurement — before any code.
.product/
├── PRODUCT.md
├── STRATEGY.md
├── METRICS.md
├── PRINCIPLES.md
├── ROADMAP.md
├── config.json
├── decisions/
├── evidence/
├── .runtime/ (disposable, gitignored)
└── .index/ (derived, gitignored)Decide — on the record
A decision becomes a Product Decision Record: facts, evidence, assumptions, alternatives, dissent, and a prediction — all in one versioned file.
siftos decidesiftos validatesiftos challengedecide structures the record — facts, evidence, assumptions, alternatives, recommendation, dissent, prediction. validate defines a Validation Contract before results exist. challenge runs an adversarial review that never modifies the record itself.
---
id: DEC-0001
title: Ship deterministic CLI before agent workflows
status: accepted
confidence: medium
reversibility: high
review_date: 2026-09-13
---
## Facts
- The deterministic core has 112 passing unit tests.
- The eval suite runs deterministic workflows against five fixtures.
## Options Considered
- A. Ship agent workflows first (rejected)
- C. Ship both at once (rejected)
## Primary Metric
Number of sample decisions that parse, validate, and appear in audit.
## Guardrails
If a sample PDR fails validation, stop and fix the core before adding more.Ship — through the gate
A Bet ships only through a deterministic gate — never because the agent decided it felt right.
siftos prioritizesiftos shipsiftos reviewprioritize compares Bets by strategy, constraint, evidence, cost, reversibility, and learning value. ship runs the deterministic Ship Gate on an accepted Bet. review compares the prediction with the outcome and extracts the learning — closing the loop.
Maintain — keep the ledger healthy
The record is only as good as the habit. SiftOS audits, retrieves, and automates — always at your explicit choice.
siftos diagnosesiftos auditsiftos showsiftos hooksdiagnose finds the highest-leverage product health issues.audit scores Decision Health with deterministic linter findings.show retrieves decision history. hooks inspects and changes lifecycle automation — and automation is never on by default.
Suggests, never blocks. The agent reports; the human decides.
Guards the record: structure and lifecycle checks before mutation.
Blocks mutations that violate the protocol. Opt-in, always explicit.
Start your first decision in 10 minutes.
No account, no database, no vendor. Copy, paste, and the record lives in your repo.
npx @felipcsousa/siftos installRuns anywhere Node 18+ is installed. MIT licensed, no telemetry.