You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
23
23
24
-
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.
24
+
Sopify uses project-level conventions 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.
25
25
26
26
### What You'll Actually Notice
27
27
28
-
- The AI does not silently make key decisions; it pauses when facts are missing or a path needs your confirmation.
29
-
- After an interruption, work resumes from the last stopping point instead of starting over.
30
-
- Plans, history, and blueprint become reusable project assets instead of disposable chat logs.
31
-
- Simple changes are not slowed down by the full process; complex work adds the necessary structure when needed.
28
+
- After an interruption, work resumes from the last stopping point — even when you switch to a different AI host or model.
29
+
- Complex changes can be independently reviewed in an isolated pass before execution.
30
+
- When a plan changes after execution was authorized, the AI cannot silently proceed — it re-confirms with you first.
31
+
- Plans, decisions, and review outcomes accumulate as reusable project assets, not disposable chat history.
32
+
- The AI pauses when facts are missing or a path needs your confirmation; simple tasks stay lightweight.
32
33
33
34
### What Kinds of Projects Benefit Most
34
35
35
36
- Multi-stage work that keeps moving in the same repository instead of one-off edits
36
37
- You're willing to manage progress with plan / blueprint artifacts and close out each stage
37
38
38
-
## What You Get After Install
39
+
###What Your AI Host Doesn't Solve
39
40
40
-
- Your host is ready to run Sopify after install.
41
-
- The first time you trigger Sopify in a project, it prepares the local `.sopify-runtime/`.
42
-
-`status` shows the current host / workspace state.
43
-
-`doctor` shows deeper installation and runtime diagnostics and repair guidance.
44
-
45
-
This guide focuses on install visibility, verification, and stable first use; repository cleanup flows are intentionally out of scope here.
41
+
| Gap |Sopify's answer |
42
+
|-----|-----------------|
43
+
| State is trapped in a single host's chat session | Portable project state — switch hosts mid-task |
44
+
| No independent quality gate | An isolated, independent review pass before execution |
45
+
| Decisions are invisible and non-auditable | Plan changes force re-confirmation — the AI cannot silently proceed |
46
+
| Each session's learning is disposable | Plans, decisions, and reviews persist as reusable project assets |
46
47
47
48
## Quick Start
48
49
49
-
### Installation
50
+
Two ways to start, depending on your repo:
51
+
52
+
### Already using Sopify? Try it directly
53
+
54
+
If your repo has `.sopify-skills/`, open any AI host (Claude, Cursor, Codex…) and ask it to continue an unfinished task — it picks up from the last stopping point, not from scratch. That's the protocol working, no runtime needed.
55
+
56
+
Full Convention walkthrough: [protocol.md §4](./.sopify-skills/blueprint/protocol.md#4-典型生命周期样例)
57
+
58
+
### First time? Install first
50
59
51
60
```bash
52
61
# Recommended: official stable one-liner
@@ -80,7 +89,7 @@ Install targets:
80
89
-`claude:zh-CN`
81
90
-`claude:en-US`
82
91
83
-
Host availability matrix:
92
+
The protocol (Convention mode) works with any host. Verified runtime integrations today:
- Sopify prepares `.sopify-runtime/` the first time you trigger it in a project workspace
100
109
-`--workspace` is an advanced prewarm path for maintainers, CI, or explicit repository setup
101
110
111
+
### How Your Workflow Changes After Install
112
+
113
+
- Use `~go` when you want Sopify to manage the full task workflow for you.
114
+
- Interrupt anytime — come back (even in a different tool) and resume from where you left off.
115
+
- Complex changes can get an independent review before execution starts.
116
+
- Run `status` to see current progress, `doctor` to troubleshoot.
117
+
102
118
### Verify Your Install
103
119
104
120
```bash
@@ -110,18 +126,6 @@ python3 scripts/sopify_doctor.py --format text
110
126
-`workspace outcome: stub_selected [continue]`: the workspace runtime entry is healthy
111
127
- Payload or bundle corruption errors (for example `global_bundle_missing`, `global_bundle_incompatible`, or `global_index_corrupted`): repair the install and retry
112
128
113
-
### Convention Mode (No Runtime)
114
-
115
-
If you only need the project protocol without installing the runtime, you can work in Convention mode directly:
116
-
117
-
1.**Read**`.sopify-skills/blueprint/` to understand the project context
118
-
2.**Write** a plan in `.sopify-skills/plan/YYYYMMDD_feature/plan.md` (must include title / scope / approach + inline tasks)
119
-
3.**Archive** to `.sopify-skills/history/YYYY-MM/` and generate `receipt.md`
120
-
121
-
See [protocol.md §4 — Lifecycle Examples](./.sopify-skills/blueprint/protocol.md#4-典型生命周期样例) for the full Convention flow (Example A), and [protocol.md §5 — Compliance Checklist](./.sopify-skills/blueprint/protocol.md#5-协议合规检查清单) for self-check items.
122
-
123
-
Any host that follows these three steps is Convention-compliant — no runtime, no installer, no CLI required.
0 commit comments