snakeying/synapse

Synapse

Codex-Based Multi-Model Workflow

Multi-model AI meets production standards Draft by Claude & Gemini · Review by Codex · Deploy with confidence

简体中文 | English

---

🤔 What is this?

Synapse is a Codex skill that orchestrates multiple AI models to help you build software:

flowchart TB
    subgraph Orchestrator["Codex (Controller)"]
        direction TB
        A1["Generates prompts"]
        A2["Rewrites drafts into production code"]
        A3["Runs verification & delivers"]
    end

    Orchestrator --> Claude["Claude(Planning · Backend diffs · Audits)"]
    Orchestrator --> Gemini["Gemini(Frontend diffs · UI/UX audits)"]

Key principle: External models (Claude/Gemini) only produce drafts — they never touch your files directly. Codex reviews every draft and rewrites it into production-quality code before applying.

---

✨ Core Features

---

🚀 Quick Start

📋 Prerequisites

💬 Usage (in Codex chat)

# End-to-end workflow: init through review
synapse workflow "Add user authentication with JWT"

# Same thing, shorter alias
synapse feat "Add user authentication with JWT"

Codex automatically orchestrates the full pipeline: init → plan → Gate → run (drafts) → apply code → verify → run (audits) → deliver.

Note: workflow and feat are Codex chat commands, not shell commands. You cannot run them directly via python synapse.py workflow ....

🔧 Manual commands (advanced)

For debugging or reproducing individual steps:

$Skill   = "\.codex\skills\synapse"
$Project = ""

# Initialize (idempotent)
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" init

# Create a plan
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" plan --task-type fullstack "Your request"

# Run an external model (prompt written by Codex)
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" run --model claude --phase plan --slug "" --prompt-file ""

# Verify (auto-detects toolchain)
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" verify

# Open web viewer
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" ui

---

🔄 Workflow Overview

init → plan → run (gate_prep) → (Gate) → run (drafts) → Codex applies code → verify → run (audits) → deliver
                         │
                   Single confirmation

---

🤖 Model Roles

Task type routing (set at plan time):

• frontend — only frontend pipeline
• backend — only backend pipeline
• fullstack — both (default, higher cost)

---

🚪 Gate

The single required user confirmation. After plan (+ gate_prep), Codex presents:

• Clarification checklist (from Claude gate_prep) with recommended defaults (single-round reply)
• Scope and acceptance criteria
• task_type selection (with recommendation)
• Stack/toolchain choice
• Allowed side effects (dependency install, lockfiles, build artifacts)
• Git/review setup
• Verification plan

After Gate confirmation, the rest proceeds automatically.

---

📌 Git Best Practices

• Use a git repo — review/audit quality is best with git diff. Run git init if needed.
• Commit after each feat — keeps the next git diff clean and focused.
• Before review — run git add -N . so new untracked files appear in git diff.

---

❓ FAQ

---

📚 More Information

• ARCHITECTURE.md — Technical details, module structure, internal mechanisms
• .codex/skills/synapse/SKILL.md — Codex execution protocol
• .codex/skills/synapse/references/*.md — Per-command specifications

---

📄 License

MIT