Sopify

A recoverable, reviewable, cross-session AI coding workflow

English · 简体中文 · Quick Start · Configuration · Contributors

---

Why Sopify?

As repositories grow, AI-assisted development runs into a hidden problem: decision context stays trapped in chat history, each new session re-derives the project state, and the user's mental model, the AI's understanding, and the codebase start to drift apart.

Sopify uses machine-readable protocols to make critical steps visible: when facts are missing, it stops and asks for them; when a branch needs a decision, it waits for confirmation; when work is interrupted, it resumes from current state instead of improvising. The basic process record is generated automatically, but the long-term compounding value still depends on consistently closing out work and maintaining project knowledge.

What You'll Actually Notice

• The AI does not silently make key decisions; it pauses when facts are missing or a path needs your confirmation.
• After an interruption, work resumes from the last stopping point instead of starting over.
• Plans, history, and blueprint become reusable project assets instead of disposable chat logs.
• Simple changes are not slowed down by the full process; complex work adds the necessary structure when needed.

What Kinds of Projects Benefit Most

• Multi-stage work that keeps moving in the same repository instead of one-off edits
• You're willing to manage progress with plan / blueprint artifacts and close out each stage

What You Get After Install

• Your host is ready to run Sopify after install.
• The first time you trigger Sopify in a project, it prepares the local .sopify-runtime/.
• status shows the current host / workspace state.
• doctor shows deeper installation and runtime diagnostics and repair guidance.

This guide focuses on install visibility, verification, and stable first use; repository cleanup flows are intentionally out of scope here.

Quick Start

Installation

# Recommended: official stable one-liner
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target codex:en-US

# Two-step install: download first, review, then run
curl -fsSL -o sopify-install.sh https://github.com/evidentloop/sopify/releases/latest/download/install.sh
sed -n '1,40p' sopify-install.sh
bash sopify-install.sh --target codex:en-US

Windows PowerShell can download the same stable asset and run it locally:

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

The repo-local / source install path remains available for developers and maintainers, but is no longer the first-screen entry:

bash scripts/install-sopify.sh --target codex:en-US
python3 scripts/install_sopify.py --target claude:en-US --workspace /path/to/project

Install targets:

• codex:zh-CN
• codex:en-US
• claude:zh-CN
• claude:en-US

Host availability matrix:

Host	Install target	Availability	Validation coverage	Notes
codex	codex:zh-CN / codex:en-US	Deep verified	Host install flow, workspace bootstrap, and runtime package smoke are verified	Suitable for daily use
claude	claude:zh-CN / claude:en-US	Deep verified	Host install flow, workspace bootstrap, and runtime package smoke are verified	Suitable for daily use

Notes:

• Use sopify status / sopify doctor for detailed capability claims and live diagnostics
• Availability expresses the current delivery tier, while Validation coverage describes what has already been validated

Installer behavior:

• Installs the selected host prompt layer and the Sopify payload
• A standard install makes your host ready to run Sopify; most users do not need --workspace
• Sopify prepares .sopify-runtime/ the first time you trigger it in a project workspace
• --workspace is an advanced prewarm path for maintainers, CI, or explicit repository setup

Verify Your Install

python3 scripts/sopify_status.py --format text
python3 scripts/sopify_doctor.py --format text

• will bootstrap on first project trigger: the host install is ready and the project-local runtime has not been prepared yet
• workspace outcome: stub_selected [continue]: the workspace runtime entry is healthy
• Payload or bundle corruption errors (for example global_bundle_missing, global_bundle_incompatible, or global_index_corrupted): repair the install and retry

Choose an Entry by Task Size

Task Type	Sopify Path
Simple change (≤2 files)	Direct execution
Medium task (3-5 files)	Light plan + execution
Complex work (>5 files / architecture change)	Full three-phase workflow

First Use

After install, open your selected host inside a repository and paste one of the prompts below.

# Simple task
"Fix the typo on line 42 in src/utils.ts"

# Medium task
"Add error handling to login, signup, and password reset"

# Complex task
"~go Add user authentication with JWT"

# Plan only
"~go plan Refactor the database layer"

# Replay / retrospective
"Replay the latest implementation and explain why this approach was chosen"

What It Looks Like (Illustrative)

[my-app-ai] Solution Design ✓

Plan: .sopify-skills/plan/20260323_auth/
Summary: JWT auth + token refresh + route guards
Tasks: 5 items

---
Next: Reply "continue" to start implementation

This is only a placeholder example of the pacing and format, not a fixed output contract; simple tasks are shorter, and complex tasks pause at checkpoints for confirmation.

For runtime gate, checkpoints, and plan lifecycle details, see How Sopify Works.

Recommended Workflow

○ User Input
│
◆ Runtime Gate
│
◇ Routing Decision
├── ▸ Q&A / replay ───────────────────→ Direct output
└── ▸ Code task
    │
    ◇ Complexity Decision
    ├── Simple (≤2 files) ────────────→ Direct execution
    ├── Medium (3-5 files) ───────────→ Light plan package
    │                                   (single-file `plan.md`)
    └── Complex (>5 files / architecture change)
        ├── Requirements ··· Fact checkpoint
        ├── Design ··· Decision checkpoint
        └── Standard plan package
            (`background.md` / `design.md` / `tasks.md`)
            │
            ◆ Execution confirmation ··· User confirms
            │
            ◆ Implementation
            │
            ◆ Summary + handoff
            │
            ◇ Optional: ~go finalize
            ├── Refresh blueprint index
            ├── Clean active state
            └── Archive → history/

◆ = execution node　◇ = decision node　··· = checkpoint (pauses, then resumes after user input)

See How Sopify Works for full details on checkpoints and plan lifecycle.

Configuration

Start from the example config:

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

Most commonly used settings:

brand: auto
language: en-US

workflow:
  mode: adaptive
  require_score: 7

plan:
  directory: .sopify-skills

Notes:

• workflow.mode supports strict / adaptive / minimal
• plan.directory only affects newly created knowledge and plan directories

Command Reference

Command	Description
~go	Automatically route and run the full workflow
~go plan	Plan only
~go exec	Advanced restore/debug entry, not the default user path
~go finalize	Close out the current metadata-managed plan

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

Sub-skills

• workflow-learning: replay, retrospective, and step-by-step explanation Docs: CN / EN

Claude uses the mirrored Claude/Skills/{CN,EN}/... layout; the links above use the Codex tree as the canonical doc entry.

Directory Structure

sopify/
├── scripts/               # install, diagnostics, and maintainer scripts
├── examples/              # configuration examples
├── docs/                  # workflow documentation
├── runtime/               # built-in runtime / skill packages
├── .sopify-skills/        # project knowledge base
│   ├── blueprint/         # long-lived blueprint
│   ├── plan/              # active plans
│   └── history/           # archived plans
├── Codex/                 # Codex host prompt layer
└── Claude/                # Claude host prompt layer

This is a simplified view of the core layout. See docs/how-sopify-works.en.md for the full workflow, checkpoints, and knowledge layout.

FAQ

Q: How do I switch language?

Update sopify.config.yaml:

language: zh-CN  # or en-US

Q: Where are plan packages stored?

By default they live under .sopify-skills/ in the project root. To change that:

plan:
  directory: .my-custom-dir

This only affects newly created directories; existing history is not migrated automatically.

Q: When should I use --workspace prewarm?

Most users do not need it. A default install is already complete; Sopify bootstraps .sopify-runtime/ automatically on the first project trigger.

Use --workspace only for maintainer validation, CI, or when you explicitly want to prewarm .sopify-runtime/ for a specific repository ahead of time. For this advanced path, use the repo-local installer:

python3 scripts/install_sopify.py --target codex:en-US --workspace /path/to/project

Q: How do I reset learned preferences?

Delete or clear .sopify-skills/user/preferences.md; keep feedback.jsonl only if you still want the audit trail.

Q: When should I run sync scripts?

When you change Codex/Skills/{CN,EN}, the mirrored Claude/Skills/{CN,EN} content, or runtime/builtin_skill_packages/*/skill.yaml, follow the validation steps in CONTRIBUTING.md.

Version History

• See CHANGELOG.md for the detailed history

License

This repository uses dual licensing:

• 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.