STARFLOW

STARFLOW is a docs-first execution kernel for Codex-driven software work. It turns a request into a bounded, resumable run with deterministic routing, explicit guardrails, evidence-backed completion, and conservative sync behavior.

This repository is the reusable STARFLOW kernel baseline. It is intended to be copied or synced into downstream repositories as the canonical starting surface.

What STARFLOW is

• A markdown-authoritative execution kernel, not a hidden runtime.
• A one-primary-track system with composable skills.
• A bounded-autonomy model with explicit controls:
  • execution_profile
  • autonomy_mode
  • artifact_mode
  • budget_policy
• An evidence-driven completion model with:
  • STATE.md as the canonical runtime/resume surface
  • resume_refs as the minimal resume bridge
  • loop_verdict as the compact loop outcome
  • evidence/INDEX.md as the mandatory evidence index

Direct REQ-driven execution and direct Codex invocation are the supported entry paths. STARFLOW no longer ships a prompt-compiler subsystem.

Quick start

1. Read AGENTS.md.
2. Read docs/ai/GETTING-STARTED.md.
3. Create a request from docs/inbox/_request-template.md, or ask Codex to snapshot your prompt into a REQ first.
4. Ask Codex to execute the request under STARFLOW.
5. Run the Kernel Check:
   • python tools/validate_starflow.py --kernel-check

Docs map

Start here:

• docs/ai/GETTING-STARTED.md
• docs/ai/BOOTSTRAP.md
• docs/ai/EXECUTION-SURFACES.md
• docs/ai/CODEX-SURFACE-OWNERSHIP.md
• docs/ai/README.md

Kernel reference:

• docs/ai/protocol/MASTER.md
• docs/ai/protocol/SCHEMAS.md
• docs/ai/protocol/GUARDRAILS.md
• docs/ai/protocol/OUTPUT-CONTRACTS.md
• docs/ai/protocol/VALIDATION-PLAN.md

What is included

• protocol docs, schemas, guardrails, and validation plan
• track catalog and docs skill catalog
• Codex wrapper layer under .agents/skills/
• reusable request and work templates
• reusable ops docs:
  • ERROR-KB.md
  • STARFLOW-TEST-LOG.md
  • _rca-template.md
• reusable standards docs
• lightweight validator:
  • tools/validate_starflow.py

The published baseline intentionally does not ship concrete REQ-* files, concrete W-* work folders, step receipts, or evidence history.

Repository structure

.
|-- AGENTS.md
|-- AGENTS.override.md
|-- KERNEL-SYNC.md
|-- .codex/config.toml
|-- .agents/skills/
|-- tools/validate_starflow.py
|-- docs/ai/
|   |-- README.md
|   |-- GETTING-STARTED.md
|   |-- BOOTSTRAP.md
|   |-- EXECUTION-SURFACES.md
|   |-- CODEX-SURFACE-OWNERSHIP.md
|   |-- protocol/
|   |-- tracks/
|   `-- skills/
|-- docs/inbox/_request-template.md
|-- docs/work/_work-template.md
|-- docs/work/_work-index.md
|-- docs/ops/
`-- docs/standards/

Compatibility notes

• Docs skill IDs remain canonical.
• Primary wrappers are listed in docs/ai/skills/_skill-manifest.md.
• Some legacy wrapper aliases remain for compatibility and migration safety. Prefer the primary wrapper names for new integrations.

Syncing into downstream repos

Use KERNEL-SYNC.md for conservative downstream updates. Use docs/ai/BOOTSTRAP.md for first-time adoption guidance.