SiftOS

Product Decision Intelligence for AI-native teams.

SiftOS is a repository-native agent skill for OpenCode, Codex and DeepSeek Harness (dsh) that gives agents persistent product context and a structured decision protocol — shape, decide, validate, challenge, build, review and learn.

Your product memory belongs to your repository, not your AI vendor.

The problem

Teams make hundreds of product decisions but rarely preserve the reasoning, evidence, assumptions and expectations behind them. Coding agents make this more acute: an idea can become code before anyone notices that a product choice was made.

SiftOS closes the loop:

Decision → Prediction → Outcome → Learning ↺

What SiftOS is

• A canonical agent skill in .agents/skills/siftos/. Product memory and explicit workflows are shared across OpenCode, Codex and dsh without migration.
• Product Decision Records (PDRs) — versioned, human-readable and agent-readable Markdown.
• Product workflows — init, decide, shape, validate, challenge, prioritize, diagnose, ship, review, show, audit, hooks.
• A deterministic core for IDs, schemas, lifecycle validation, linting, search, guard policy and Ship Gate checks.
• Optional lifecycle adapters. Installing SiftOS never enables automatic intervention; the user explicitly chooses advisory, balanced, strict or a custom policy.
• Local-first, Git-native — .product/ is the source of truth. No remote database is required.

SiftOS does not replace human judgment. The human owns every decision.

Quickstart

npx @felipcsousa/siftos install
siftos init

Full walkthrough — first bet in 10 minutes: docs/quickstart.md.

Then ask your agent:

Initialize SiftOS for this product.
Should we remove the credit card requirement from trial?

init creates a scaffold. Placeholder-only files such as PRODUCT.md full of Unknown. are intentionally reported by siftos doctor as not ready until useful context has been established.

Automatic hooks remain OFF after install/init. Opt in explicitly:

siftos hooks set advisory
siftos hooks set balanced
siftos hooks set strict

Memory layout

.product/
├── PRODUCT.md
├── STRATEGY.md
├── METRICS.md
├── PRINCIPLES.md
├── ROADMAP.md
├── config.json
├── decisions/
├── evidence/
├── .runtime/          disposable, gitignored
└── .index/            derived, gitignored

The skill definition and product memory are never mixed.

Product Decision Record

---
id: DEC-0042
title: Remove mandatory credit card from trial
status: accepted
created_at: 2026-08-13
updated_at: 2026-08-13
goal: improve-activation
bet_class: offense
confidence: medium
reversibility: high
cost_of_delay: medium
review_date: 2026-09-13
agent_workflow_version: decide-v1
---

A PDR separates facts, evidence, inferences, assumptions, unknowns, alternatives, AI recommendation, final human decision, expected outcome, metrics, guardrails, dissent and revisit conditions. Predictions are written before outcomes and preserved through review.

Lifecycle:

draft → shaping → validating → ready → accepted → building → shipped → measuring → reviewed

with proposed, rejected, cancelled, paused, failed and superseded retained where applicable.

Workflows

| Workflow | Purpose | | --- | --- | | init | Build persistent product context progressively. | | decide | Structure a product choice with evidence, alternatives, dissent and prediction. | | shape | Turn an idea into a falsifiable Bet with scope and an SVT. | | validate | Define a Validation Contract before results exist. | | challenge | Adversarially review an idea/PDR without modifying it. | | prioritize | Compare Bets using strategy, constraint, evidence, cost and learning value. | | diagnose | Surface the highest-leverage product health issues. | | ship | Run the deterministic product Ship Gate. | | review | Compare prediction with outcome and extract learning. | | show | Retrieve decision history. | | audit | Decision Health + deterministic linter findings. | | hooks | Inspect/change automatic lifecycle policy. |

Automatic hooks

SiftOS separates three states:

Installed ≠ Enabled ≠ Observed

Installing an adapter never enables it. A hook is only active when the user has enabled it and the runtime has actually observed it fire.

Presets:

| Preset | Behavior | | --- | --- | | off | Manual SiftOS only. | | advisory | Observe/recommend, never block. | | balanced | Gate unresolved L2/L3 mutations; Codex closeout may request one continuation. | | strict | Stronger gating, including unknown mutations where applicable. | | custom | Any per-hook combination. |

Config precedence is session override → repository config → global default → preset. Build anyway remains available because the human owns the decision.

Known per-hook entries are schema-validated and must include enabled. A malformed hook block is never partially interpreted. siftos hooks / doctor report the configuration error, and the before_mutation boundary fails closed until the policy is unambiguous; non-critical lifecycle hooks remain inert.

Product Guard semantics

Product Guard classifies work as L0 technical, L1 minor, L2 material or L3 strategic. In balanced, an unresolved L2/L3 remains blocked until an authorizing resolution exists. Retrying a tool call is never authorization.

Authorizing resolutions:

• prototype
• existing_bet pointing to an active accepted, building, shipped or measuring PDR/Bet
• build_anyway

shape, validate and reconsider are valid next steps and may update .product/, but they do not silently authorize production mutation. Manual Guard calls are independent intents unless the caller intentionally reuses an explicit --turn-id, so one manual bypass is not sticky.

The deterministic fallback also distinguishes mutation effect from product level: tests/docs/examples/fixtures are non-product targets, npm test and typecheck are verification, while npm run build is a mutation because it can write artifacts. The TypeScript core and standalone hook runtime consume the same policy data and are covered by parity evals.

Harness capability matrix

Product memory and explicit skills are shared across all supported harnesses. Automatic lifecycle integration is intentionally reported by actual capability rather than claimed as perfect parity.

| Capability | Codex | OpenCode | dsh | | --- | --- | --- | --- | | Shared .agents/skills/siftos workflows | Yes | Yes | Yes (native rank 200) | | Before/after mutation guard | Native hook adapter | Native plugin hook | tools/pre-execute + tools/result | | Session lifecycle observation | Yes | Yes | agent/session-start / agent/disposed | | Compaction preservation | PreCompact + session context | compaction plugin hook | agent/session-start source compact + capsule inject | | Prompt-submit context injection | Native UserPromptSubmit | No documented 1:1 equivalent; degraded | agent/pre-step (native) | | Stop-style forced closeout continuation | Native Stop | No documented 1:1 equivalent; advisory at idle | agent/turn-stopping + agent.steer (native, capped at one) |

Codex uses the harness JSON contracts for context injection, PreToolUse.permissionDecision, and Stop continuation. OpenCode installs a real repository plugin under .opencode/plugins/siftos.js using documented before/after tool hooks, session events and compaction context. OpenCode starts a fresh runtime scope on each observed session.created; at idle, SiftOS can use a unique building Bet when one exists or explicitly report that mutations occurred without a uniquely attachable Bet. When exact parity is unavailable, siftos doctor reports the real installed/observed state instead of inventing capability.

siftos install preserves non-SiftOS entries already present in .codex/hooks.json, refuses to overwrite an unrelated .opencode/plugins/siftos.js, and replaces its own skill directory on reinstall so removed package files do not survive as stale artifacts.

dsh installs a home-level Cordis plugin ($DSH_HOME/plugins/siftos + a marked cordis.patch.yml insert row) whose documented contracts are tools/pre-execute mutation gating, tools/result tracking, agent/pre-step prompt intake, and agent/turn-stopping closeout with exactly one agent.steer continuation. dsh is developer-preview; when plugin APIs change, siftos doctor keeps reporting the installed artifacts honestly instead of assuming runtime fire.

Ship Gate

siftos ship <DEC-XXXX> and automatic closeout share the same deterministic status policy and checks. The gate applies to active accepted, building, shipped and measuring Bets; reviewed and superseded are historical/ terminal states and return NOT_REQUIRED.

Checks include target user, problem/goal, expected outcome/metric, success threshold, baseline, instrumentation, guardrails, revisit condition and scope. It controls SiftOS lifecycle state; it is not deployment authorization or a security boundary.

Deterministic linters

The current linter set catches structural product-decision problems including missing goals/alternatives/metrics/review conditions, assumptions duplicated as facts, missing dissent, missing SVTs/scope, missing human decisions, stale reviews/evidence, missing guardrails and conflicting status combinations.

These linters are deterministic. Semantic product judgment still belongs to the agent workflows; SiftOS does not pretend that string rules alone constitute complete product judgment.

CLI

siftos install
siftos init
siftos validate
siftos audit
siftos search <query>
siftos next-id
siftos show <DEC-XXXX>
siftos context [<query>]
siftos hooks
siftos hook enable|disable <hook>
siftos ship <DEC-XXXX>
siftos roadmap
siftos guard check <path>
siftos scope <DEC-XXXX> <path...>
siftos doctor
siftos version

Set SIFTOS_TODAY=YYYY-MM-DD to pin time-dependent checks in deterministic tests.

siftos doctor

Doctor is deliberately adversarial. It distinguishes:

• core/manual health from lifecycle-automation health;
• skill compatibility from lifecycle-adapter installation;
• installed hooks from enabled hooks;
• enabled hooks from observed hooks;
• scaffold files from useful product context;
• valid hook configuration from ambiguous/malformed policy.

A directory full of Unknown. is a valid scaffold but not a healthy product context. Conversely, a deliberately manual-only repository can be healthy even without Codex/OpenCode lifecycle adapters; automation is reported separately as off, healthy or degraded.

Security

• No remote SiftOS database is required.
• Canonical memory lives in the repository.
• SiftOS never commits automatically.
• Product Guard is not a security/sandbox boundary.
• Content read by a coding agent may be processed by that agent's model provider even though SiftOS persistence itself is local.

Repository layout

src/        deterministic core + shipped CLI entrypoint
skill/      canonical agent skill, references, scripts and harness adapters
evals/      deterministic and lifecycle eval suites
test/       unit/integration tests

Development

npm install
npm run typecheck
npm test
npm run build
node evals/run.mjs
node evals/hooks/run.mjs

CI runs both deterministic workflow evals and lifecycle-hook evals. The latter exercise the shipped entrypoint and native adapter contracts so a regression in automatic Product Guard cannot be hidden by unit tests of the policy table.

LLM-dependent judgment quality (decide, challenge, review, etc.) still requires a separate live behavioral eval harness; deterministic passing tests do not claim to prove product-judgment superiority.

Contributing

See CONTRIBUTING.md.

License

MIT © SiftOS contributors.