Sopify

Resumable AI coding — ask first, plans stay with the repo

English · 简体中文 · Quick Start · Contributors

---

AI coding tools are fast. But when they jump to code before the facts are clear, speed turns into rework. Sopify is a development process protocol layer for AI coding: in managed workflows, the host asks before coding when requirements are incomplete or a decision still needs you.

Sopify stores plans and verification receipts in .sopify/ as project files tracked by git. Only the local resume pointers stay out of git. In the same repo, explicitly ask to continue or use ~go to resume managed work from those files on any supported host.

No new editor, no new CLI. Install into the host you already use — Codex, Claude, Qoder, or Copilot.

Design principles:

• Stop when unsure — score every requirement; ask before assuming
• Resume from anywhere — plans and verification receipts are tracked in .sopify/; open the repo on any host and pick up where you left off
• Trace every decision — plans, choices, and reviews persist in .sopify/

What Sopify prevents:

• Premature coding — AI starts changing code before missing facts or decisions are resolved
• Lost context — switching hosts, machines, or teammates forces the work to be re-explained
• Forgotten decisions — important tradeoffs disappear into chat history instead of becoming project artifacts

See the workflow diagram, checkpoints, and resume flow →

See It In Action

Quick Start

curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target codex:en-US

Sopify requires Python 3.11 or newer; the installer checks before downloading. This command installs Sopify only.

Optional: append --with-evidentloop to the same command to install EvidentLoop; see Installation.

After install, use ~go to start a managed workflow. See Installation for other hosts, Windows, and how to review the installer before running it.

Already in a Sopify-managed repo? Explicitly ask to continue or use ~go to resume the current plan. Ordinary questions and small fixes are handled directly without automatically entering the previous plan workflow.

Why Sopify?

When requirements are unclear, it stops to plan first. You say "add a caching layer." Sopify doesn't start coding — it plans first: analyze, design, split into tasks, then save to .sopify/plan/. Only after you confirm the plan does it write code. Every line changed traces back to a decision.

Your teammate picks up where you left off. You start a feature in Codex, finish the design, and implement two of four tasks. Next week your teammate opens the same repo in Claude, types ~go. Sopify reads the checkpoint and continues from task 3 — no handoff doc, no re-explaining context.

Every decision leaves a trace. A month later, someone asks why the cache key includes the user ID. The answer is in .sopify/plan/ — the requirement that prompted the decision, the design that resolved it, the review that approved it.

Product Form

The host LLM executes. Sopify supplies shared workflow rules and preserves plans, decisions, and verification evidence as project files in .sopify/. Local resume pointers remain on the machine.

Sopify does three things:

• Shared workflow rules — supported hosts load the same Sopify workflow rules, so switching hosts does not change the process and boundaries you already confirmed
• Git-tracked project record — plans, decisions, and verification evidence travel with the repository; local pointers do not
• Explicit resume and closeout — ask to continue or use ~go before the host resumes; ~go finalize archives the plan only after delivery evidence is ready

Architecture Details

For readers who want the internal layering behind the product form, the technical structure is below.

Installation

Review before running:

curl -fsSL -o sopify-install.sh https://github.com/evidentloop/sopify/releases/latest/download/install.sh
less sopify-install.sh          # review before running
bash sopify-install.sh --target codex:en-US

Windows PowerShell:

iwr https://github.com/evidentloop/sopify/releases/latest/download/install.ps1 -OutFile sopify-install.ps1
Get-Content sopify-install.ps1 | more
.\sopify-install.ps1 --target codex:en-US

Host support:

Host	Tier	Target	Notes
Codex	PROTOCOL_VERIFIED	codex:en-US / codex:zh-CN	Full capability continuation
Claude	PROTOCOL_VERIFIED	claude:en-US / claude:zh-CN	Full capability continuation
Qoder	PROTOCOL_VERIFIED	qoder	Validated on Qoder CLI
Copilot	BASELINE_SUPPORTED	copilot:en-US / copilot:zh-CN	Prompt-only; payload uplift planned

Pass --workspace <path> to target another repo, --language <lang> to control output language.

EvidentLoop is an optional code-change audit tool. It turns a local Git diff into an interactive report, ties audit findings to changed lines, and lets users update the report through feedback. To install the current official CLI and Skill with Sopify, or reuse healthy existing components, pass --with-evidentloop explicitly:

bash sopify-install.sh --target codex:en-US --with-evidentloop

Healthy existing components are reused without automatic upgrades. The Copilot Skill is project-scoped; Sopify does not commit or update it. See Getting Started for prerequisites, host-specific paths, and the local/cloud boundary.

For the full setup guide, see Getting Started. For a step-by-step demo, see External Repo Quickstart.

Command Reference

Command	Description
~go	Automatically route and run the full workflow (auto-resumes if active plan exists)
~go plan	Plan only
~go finalize	Close out the active plan

Most users only need ~go and ~go plan; maintainer validation commands live in CONTRIBUTING.md.

Configuration

cp examples/sopify.config.yaml ./sopify.config.yaml

brand: auto
language: en-US

workflow:
  mode: adaptive   # strict | adaptive | minimal
  require_score: 7

Directory Structure

sopify/
├── scripts/               # install, diagnostics, and maintainer scripts
├── examples/              # configuration examples
├── docs/                  # workflow guides and developer references
├── sopify_writer/         # protocol asset writer library
├── sopify_contracts/      # schema definitions and shared data structures
├── skills/                # prompt-layer source of truth
├── installer/             # host adapters and install orchestration
└── .sopify/               # project protocol root
    ├── blueprint/         # protocol spec, design baseline, reduction targets
    ├── plan/              # active plans + receipts
    └── history/           # archived plans + receipts

See How Sopify Works for the full workflow, checkpoints, and knowledge layout.

Version History

• See CHANGELOG.md for the detailed history

License

• Code and config: Apache 2.0, see LICENSE
• Documentation: CC BY 4.0, see LICENSE-docs

Contributing

For user-visible behavior changes, update both README.md and README.zh-CN.md when needed, then follow CONTRIBUTING.md for validation.