Sopify

AI coding that asks before it acts

English · 简体中文 · Quick Start · Contributors

AI coding tools are fast. But when they jump to code without understanding what's needed, speed becomes rework. Sopify is a development process protocol layer for AI coding — it turns plans, decisions, handoffs, and verification records into project assets, so work can stop, resume, and be traced.

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, decisions, and verification records 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

After install, use ~go to start a managed workflow. See Installation for other hosts, audit-first install, and Windows.

Already in a Sopify-managed repo? Open any AI host and continue — it picks up from where you left off.

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.

Architecture

The host LLM executes. Sopify preserves auditable development assets — plans, decisions, handoffs, and verification evidence — in .sopify/, accessible across sessions, hosts, and teammates.

How Sopify achieves stability and quality:

• Same rules on every host — Claude, Codex, Qoder, and Copilot load the same Sopify instructions, so switching hosts doesn't reset the workflow
• Project assets tracked in git — plans, decisions, and verification records live in .sopify/; only the two local pointer files (active_plan.json, current_handoff.json) are gitignored
• Resumes from where you stopped — the host reads the current plan, picks up the last handoff, and checks what's already been verified before continuing
• Runtime retired; workflow retained — the analyze → design → develop → finalize workflow is unchanged; what changed is that rules live in files, not a runtime process

Installation

Audit-first install:

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:

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

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

Command Reference

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.