Sententia

Strict Multi-Model Orchestration for Codex CLI

Coordinates Claude Code and Gemini CLI under Codex's control
Human approval gates · Scope isolation · Automated validation

简体中文 | English

---

🤔 What is this?

Sententia is a Codex skill that orchestrates multiple AI backends with strict safety controls:

flowchart TB
    subgraph Orchestrator["Codex (Orchestrator)"]
        direction TB
        A1["Splits tasks into steps"]
        A2["Assigns owner per step"]
        A3["Enforces scope & creates commits"]
    end

    Orchestrator --> Claude["Claude<br/>(Backend)"]
    Orchestrator --> Gemini["Gemini<br/>(Backend)"]
    Orchestrator --> Fallback["Codex<br/>(Fallback)"]

Loading

---

✨ Core Features

Feature	Description
🚪 Dual Gates	Human approval required before execution (Gate A: plan, Gate B: spec)
🎯 Scope Audit	Changes outside declared paths are auto-reverted
🔒 Baton Lock	Only one backend writes at a time
🚫 Commit Guard	Backends cannot commit; Codex manages all commits
✅ Strict Checks	format / lint / typecheck / unit / e2e / build must pass
🔄 Degraded Mode	Graceful fallback when backends unavailable

---

🚀 Quick Start

1️⃣ Prerequisites

sententia doctor

Tool	Required
git	Yes
uv	Yes
claude / gemini	At least one

2️⃣ Usage

# New project or complex task
sententia workflow "Build a weather dashboard with React frontend and Express API"

# Add feature to existing project
sententia feat "Add user authentication with JWT"

# Fix a bug
sententia fix "Login button not responding"

---

📋 Workflow Overview

doctor → scout → [analyze] → [research] → plan → spec → execute → validate → review
                                            │       │
                                         Gate A  Gate B

Stage	Output	Writes Code
analyze	analysis.md
research	research.md
plan	plan.md
spec	spec.md
execute	execute.md	Yes
validate	validate.md
review	review.md

---

🔑 Gates

Gate	When	What
Gate A	After plan	Approve stack, boundaries, checks
Gate B	After spec	Approve detailed execution steps

Before gates are approved, backends are read-only. (Repo-read-only; MCP/tools are allowed. Repo changes are blocked by Sententia's git plan guard.)

---

Boundaries Override

When auto-detection is inaccurate:

uv run ... sententia.py config-set-boundaries `
  --frontend-root "apps/web" `
  --backend-root "apps/api"

Strict Checks

Strict check commands live in .sententia/config.json under strict_checks. Each value is either a command string, or N/A (skip). N/A must be explicitly approved at Gate A and logged in decisions.md with a reason.

---

❓ FAQ

Q: Why two gates instead of one?

Gate A confirms the approach (stack, boundaries, checks). Gate B confirms the detailed spec. This prevents wasted effort if the approach is wrong.

Q: What if a backend writes outside its scope?

Changes are auto-reverted. Codex then decides: retry with clearer instructions, split the step, switch to another backend, or expand scope (logged to decisions.md).

Q: Can I use only Claude or only Gemini?

Yes. Sententia works with a single backend. The other steps are reassigned to the available backend or Codex itself.

---

📚 More Information

• ARCHITECTURE.md — Technical details, execution flows, internal mechanisms
• .codex/skills/sententia/references/*.md — Execution playbooks
• .codex/skills/sententia/assets/templates/*.md — Templates

---

📜 License

MIT