evidentloop/sopify

Sopify – Resumable, plan‑first AI coding

What it is – Sopify is a lightweight protocol layer that sits on top of existing AI‑coding assistants (GitHub Codex, Anthropic Claude, Qoder, GitHub Copilot). It makes the assistant stop when the requirements are unclear, forces a plan to be recorded, and stores that plan plus verification evidence in a hidden .sopify/ folder that is tracked by Git. When you (or a teammate) later open the same repository on any supported host, you can type ~go and the host will automatically resume the saved workflow from the next unfinished task.

Why it matters – Many AI‑coding tools jump straight to code, which often leads to:

• premature changes before facts are known,
• lost context when switching machines or LLM hosts, and
• undocumented design decisions. Sopify solves these by turning the planning and decision‑making steps into project artifacts that travel with the repo.

---

Core concepts

Concept	What it does
Managed workflow	The host asks for clarification, creates a design, splits work into tasks, and writes the plan to .sopify/plan/. No code is emitted until you explicitly confirm.
Resume pointers	A tiny local file (outside Git) remembers which step you were on. Typing ~go on any host reads the plan and continues from the next task.
Traceability	Every requirement, design choice, and review is saved as a plain‑text/JSON file in .sopify/. You can later inspect why a particular line of code exists.
Host‑agnostic	The same .sopify/ files are understood by Codex, Claude, Qoder, and (to a limited extent) Copilot, so teams can switch assistants without breaking the process.

---

Quick start (from the README)

# Install only the Sopify layer for a specific host (here Codex, English US)
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh \
  | bash -s -- --target codex:en-US

Requires Python 3.11+.

After installation, open a repo that already contains a .sopify/ folder (or start a new one) and run:

~go            # start or resume the full workflow
~go plan       # only create a plan, no code yet
~go finalize   # close the active plan after delivery evidence is ready

The installer can be reviewed before execution (curl … -o install.sh && less install.sh). Windows users have an equivalent PowerShell script.

Configuration (example)

# sopify.config.yaml placed at the repo root
brand: auto
language: en-US
workflow:
  mode: adaptive   # strict | adaptive | minimal
  require_score: 7 # minimum confidence score before the host proceeds automatically

Configuration lives alongside the code and is itself version‑controlled.

Directory layout (relevant parts)

.sopify/
├─ blueprint/   # baseline design specs, reduction targets
├─ plan/        # active plans + verification receipts
└─ history/     # archived (finalized) plans

All other source files (sopify_writer/, skills/, etc.) implement the protocol but are not required to be edited by end users.

Typical workflow

1. Ask – You request a feature (e.g., “add a caching layer”).
2. Plan – Sopify prompts the host to analyze requirements, produce a design, and split the work into tasks. The plan is saved under .sopify/plan/.
3. Confirm – You approve the plan; only then does the host start generating code.
4. Code – The host writes code, attaching a receipt that links each change back to the originating task.
5. Resume – If you stop mid‑feature, the local resume pointer remembers the last completed task. Opening the repo on another host and typing ~go picks up at task N+1.
6. Finalize – When the feature is done, ~go finalize archives the plan and its evidence to .sopify/history/.

---

Use cases

• Team hand‑offs – A developer can start a feature in Codex, hand the repo to a teammate using Claude, and the teammate resumes without re‑explaining context.
• Auditability – Managers can review .sopify/plan/ files to see why a particular implementation decision was made.
• Cross‑language projects – Because the protocol files are language‑agnostic, the same workflow works for Python, JavaScript, etc., as long as the host supports the target language.

---

Architecture snapshot (as described in the README)

• Protocol kernel – Core logic that interprets ~go commands and manages resume pointers.
• Default workflow – A set of rules (score thresholds, adaptive mode) that dictate when the host must ask for clarification.
• Knowledge layer – The .sopify/ files that store plans, design blueprints, and verification receipts; these travel with the Git repo.

---

License

• Code & configuration – Apache 2.0
• Documentation – Creative Commons BY 4.0

---

Bottom line

Sopify does not replace an LLM; it adds a disciplined, git‑tracked process that forces planning, preserves decisions, and lets any supported AI‑coding host pick up exactly where the last session left off. For teams that rely on AI assistants but need reproducibility and audit trails, Sopify provides a minimal‑overhead, host‑agnostic solution.