synapse

Category: Tools & Productivity | Uploader: snakeying | Downloads: 0 | Version: v1.0（Latest）

Codex-led multi-model workflow (Codex + Claude + Gemini). Use when the user asks to run `synapse <cmd> ...` to generate draft diffs/audits and persist artifacts to `./.synapse/**`.

Changelog: Source: GitHub https://github.com/snakeying/Synapse

Directory Structure

Current level: .codex/skills/synapse/

📁 assets/
- 📁 ui/
  - 📄 index.html 23.2 KB
- 📄 defaults.json 800 B
📁 references/
- 📄 feat.md 213 B
- 📄 init.md 437 B
- 📄 pack.md 472 B
- 📄 plan.md 1.2 KB
- 📄 run.md 1.5 KB
- 📄 ui.md 1.2 KB
- 📄 verify.md 605 B
- 📄 workflow.md 2.5 KB
📁 scripts/
- 📁 _synapse/
  - 📁 verify/
    
    📄 __init__.py 35 B
    
    📄 dotnet.py 454 B
    
    📄 golang.py 376 B
    
    📄 node.py 2.4 KB
    
    📄 python.py 2.2 KB
    
    📄 rust.py 378 B
    
    📄 types.py 539 B
  - 📄 __init__.py 60 B
  - 📄 agents_md.py 3.6 KB
  - 📄 cmd_init.py 1.0 KB
  - 📄 cmd_pack.py 2.3 KB
  - 📄 cmd_plan.py 5.7 KB
  - 📄 cmd_run.py 6.9 KB
  - 📄 cmd_ui.py 6.8 KB
  - 📄 cmd_verify.py 5.8 KB
  - 📄 common.py 1.1 KB
  - 📄 config.py 611 B
  - 📄 context_git.py 2.2 KB
  - 📄 context_pack.py 3.6 KB
  - 📄 context_queries.py 2.0 KB
  - 📄 context_rg.py 3.5 KB
  - 📄 context_sensitivity.py 2.8 KB
  - 📄 context_snippets.py 3.1 KB
  - 📄 file_ops.py 3.3 KB
  - 📄 llm.py 3.5 KB
  - 📄 llm_protocol.py 1.8 KB
  - 📄 llm_runner.py 6.8 KB
  - 📄 llm_stream.py 899 B
  - 📄 paths.py 4.8 KB
  - 📄 process_utils.py 1.3 KB
  - 📄 safety.py 2.5 KB
  - 📄 state.py 6.4 KB
  - 📄 storage_paths.py 1.9 KB
- 📄 synapse.py 5.2 KB
📄 SKILL.md 3.6 KB

SKILL.md

---
name: synapse
description: Codex-led multi-model workflow (Codex + Claude + Gemini). Use when the user asks to run `synapse <cmd> ...` to generate draft diffs/audits and persist artifacts to `./.synapse/**`.
---

# Synapse (Codex Skill)

Synapse is a **project-local workflow runner** driven by **Codex (main controller)**.

## Models (roles)

- **Codex (main controller)**: decides routing, writes prompts, applies final code, runs verification, and delivers
- **Claude**: planning/architecture/risks + backend draft diffs + general code audit
- **Gemini**: frontend/UI draft diffs + UI/UX + accessibility audit (only when `task_type` includes frontend)

Artifacts are written under `./.synapse/**` in the *target project root*.

## Hard rules (must follow)

- Only handle requests that start with `synapse <cmd> ...` (no slash commands).
- Before running anything: open `references/<cmd>.md` and summarize (purpose, usage, models, writes/side effects, and any safety/confirmation requirements).
- If any **script-level** CLI args are unclear (`init/pack/plan/run/verify/ui`), run `synapse.py <cmd> --help` (via `uv`) and follow the output.
- Run Synapse scripts via `uv`:

```powershell
uv run --no-project python <SKILL_DIR>/scripts/synapse.py --project-dir <PROJECT_DIR> <cmd> ...
```

- Treat any external diff as a **draft**. Do **not** apply verbatim; Codex rewrites to production quality.
- Prompts are **not hardcoded in scripts**. Codex must generate prompts and pass them via `synapse run --prompt-file ...`.
- `workflow`/`feat` are end-to-end (Codex-orchestrated) meta commands. Treat `references/workflow.md` as the source of truth for the exact steps and Gate requirements (including `gate_prep` + single-round Gate).
- `task_type` rules:
  - If the user explicitly sets `--task-type`, respect it.
  - If omitted: default to `fullstack` (info-complete; higher cost) and still present `frontend/backend/fullstack` options + Codex recommendation at the Gate.
- Git safety:
  - Prefer a clean working tree. If it's dirty, surface it at the Gate and ask how to proceed (stash/commit/abort).
  - If the project is not a git repo, propose `git init` at the Gate (review quality is best with git).

## Global flags (common)

- `--project-dir <dir>`: directory inside the target project (default: `.`)
- `--resume-gemini <SESSION_ID>` / `--resume-claude <SESSION_ID>`
- `--resume <SESSION_ID>`: alias for `--resume-gemini` (back-compat)
  - If both `--resume` and `--resume-gemini` are provided with different values, Synapse errors to avoid silent confusion.

## Command map

User-level commands (typed in Codex chat):

- `workflow`, `feat`

Script-level subcommands (Codex runs via `uv`):

- `init`, `pack`, `plan`, `run`, `verify`, `ui`

## Script guarantees

- Project root detection: `git rev-parse --show-toplevel` (fallback: current directory).
- Artifacts always go under `./.synapse/**` (plans/context/logs/patches/state/index).
- Writes are guarded by `assets/defaults.json:safety.allowed_write_roots` (hard fail if a write would escape these roots).
- `init` only writes: `AGENTS.md`, `.gitignore`, `./.synapse/**` (idempotent).
- `verify` may create **project-local toolchain artifacts** (lockfiles, `.venv/`, `node_modules/`, build outputs) as a side effect.
- External model calls use local `claude` + `gemini` CLIs in stream-json mode (`session_id` captured; resume supported). Synapse never enables “auto-approve” modes (Gemini runs with `--approval-mode default`; Claude runs with `--permission-mode plan --tools "" --strict-mcp-config`).
- `ui` starts a local read-only web viewer for `.synapse/**` (prompts/outputs/patches/logs/state).

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

synapse

Directory Structure

SKILL.md

Report

Notice