{"id":50293113,"url":"https://github.com/evidentloop/sopify","last_synced_at":"2026-05-28T07:01:54.831Z","repository":{"id":332737735,"uuid":"1134772473","full_name":"evidentloop/sopify","owner":"evidentloop","description":"Resumable, traceable AI coding — decisions and history stay with the project","archived":false,"fork":false,"pushed_at":"2026-05-27T14:09:34.000Z","size":5177,"stargazers_count":147,"open_issues_count":0,"forks_count":12,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-05-27T15:25:38.021Z","etag":null,"topics":["adaptive-workflow","ai-agent","ai-coding","claude","codex","config-driven","skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evidentloop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T07:20:20.000Z","updated_at":"2026-05-27T14:13:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/evidentloop/sopify","commit_stats":null,"previous_names":["li-weixin/sopify-skills","sopify-ai/sopify-skills","sopify-ai/sopify","evidentloop/sopify"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/evidentloop/sopify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentloop%2Fsopify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentloop%2Fsopify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentloop%2Fsopify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentloop%2Fsopify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evidentloop","download_url":"https://codeload.github.com/evidentloop/sopify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentloop%2Fsopify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33597808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adaptive-workflow","ai-agent","ai-coding","claude","codex","config-driven","skills"],"created_at":"2026-05-28T07:01:49.501Z","updated_at":"2026-05-28T07:01:54.820Z","avatar_url":"https://github.com/evidentloop.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sopify\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./assets/logo.svg\" width=\"120\" alt=\"Sopify Logo\" /\u003e\n\n**Resumable, traceable AI coding — decisions and history stay with the project**\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\n[![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs)\n[![Version](https://img.shields.io/badge/version-2026--05--28.044700-orange.svg)](#version-history)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)\n\nEnglish · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [Contributors](./CONTRIBUTORS.md)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./assets/sopify-cover.jpg\" width=\"800\" alt=\"Sopify — Resumable, traceable AI coding\" /\u003e\n\u003c/div\u003e\n\n---\n\nWhen facts are missing, Sopify stops and asks. When a decision needs your approval, it waits. When work is interrupted, it resumes from the last stopping point — even across different AI hosts.\n\n## Quick Start\n\n```bash\ncurl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target codex:en-US\n```\n\nAfter install, use `~go` to start a managed workflow. See [Installation](#installation) for other targets, platforms, and verification.\n\n**Already in a Sopify-managed repo?** Open any AI host and continue the unfinished task — it picks up from where you left off. [Full walkthrough →](./docs/how-sopify-works.en.md)\n\n| Step | What happens |\n|------|-------------|\n| Start | Ask the host to begin or continue a task |\n| Pause | Sopify stops when facts are missing or a decision needs you |\n| Resume | Work picks up from project state — even on a different host |\n\n---\n\n## Why Sopify?\n\nAs 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.\n\nSopify uses project-level conventions to make critical steps visible. The basic process record is generated automatically, but the long-term compounding value still depends on consistently closing out work and maintaining project knowledge.\n\n| Gap | Sopify's answer |\n|-----|-----------------|\n| State is trapped in a single host's chat session | Portable project state — switch hosts mid-task |\n| No independent quality gate | An isolated, independent review pass before execution |\n| Decisions are invisible and non-auditable | Plan changes force re-confirmation — the AI cannot silently proceed |\n| Each session's learning is disposable | Plans, decisions, and reviews persist as reusable project assets |\n\n## Architecture\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./assets/sopify-architecture.svg\" width=\"800\" alt=\"Sopify Architecture — Evidence \u0026 Authorization Layer\" /\u003e\n\u003c/div\u003e\n\nUser input flows through a host adapter (Codex, Claude, Copilot) into the Core Protocol, where every action is proposed, validated, gated, and receipted. The Validator is the sole authorizer — the host LLM is only a proposal source. Knowledge layers (blueprint, plan, history) persist across sessions and hosts.\n\n## Installation\n\nTwo-step install (recommended for first-time review):\n\n```bash\ncurl -fsSL -o sopify-install.sh https://github.com/evidentloop/sopify/releases/latest/download/install.sh\nsed -n '1,40p' sopify-install.sh\nbash sopify-install.sh --target codex:en-US\n```\n\nWindows PowerShell:\n\n```powershell\niwr https://github.com/evidentloop/sopify/releases/latest/download/install.ps1 -OutFile sopify-install.ps1\nGet-Content sopify-install.ps1 -TotalCount 40\n.\\sopify-install.ps1 --target codex:en-US\n```\n\nThe repo-local install path remains available for developers and maintainers:\n\n```bash\nbash scripts/install-sopify.sh --target codex:en-US\npython3 scripts/install_sopify.py --target claude:en-US --workspace /path/to/project\n```\n\nInstall targets:\n\n- `codex:zh-CN`\n- `codex:en-US`\n- `claude:zh-CN`\n- `claude:en-US`\n- `copilot:zh-CN`\n- `copilot:en-US`\n\nThe protocol works with any host. Verified runtime integrations today:\n\n| Host | Install target | Availability | Validation coverage | Notes |\n|------|----------------|--------------|---------------------|-------|\n| `codex` | `codex:zh-CN` / `codex:en-US` | Deep verified | Host install flow, workspace bootstrap, and runtime package smoke are verified | Suitable for daily use |\n| `claude` | `claude:zh-CN` / `claude:en-US` | Deep verified | Host install flow, workspace bootstrap, and runtime package smoke are verified | Suitable for daily use |\n| `copilot` | `copilot:zh-CN` / `copilot:en-US` | Workspace ready | Workspace bootstrap, instruction distribution, and workspace marker are verified | Trigger wiring coming next |\n\nNotes:\n\n- Use `sopify status` / `sopify doctor` for detailed capability claims and live diagnostics\n- `Availability` expresses the current delivery tier, while `Validation coverage` describes what has already been validated\n\n### Setup Paths\n\n| You want to… | Script | Command |\n|--------------|--------|---------|\n| Set up Codex / Claude | `install.sh` | As shown above — installs host prompt layer + Sopify payload |\n| Set up Copilot | `install.sh` | `curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh \\| bash -s -- --target copilot` |\n\n- `install.sh --target codex:... / claude:...` installs the selected host prompt layer and the Sopify payload. Most users do not need `--workspace`; that is an advanced prewarm path for maintainers or CI.\n- `install.sh --target copilot` bootstraps the current workspace, creates `.sopify-skills/sopify.json`, updates `.gitignore`, and distributes Copilot instruction files. Pass `--workspace \u003cpath\u003e` to target another repo, `--language \u003clang\u003e` to control output language, or `--no-copilot` to skip Copilot files.\n- `bootstrap.sh` remains available as a compatibility alias and forwards to `install.sh --target copilot`.\n\nFor the full setup guide, see [Getting Started](./docs/getting-started.md). For a step-by-step demo, see [External Repo Quickstart](./examples/external-repo-quickstart/README.md).\n\n### After Install\n\n- Use `~go` when you want Sopify to manage the full task workflow for you.\n- Interrupt anytime — come back (even in a different tool) and resume from where you left off.\n- Complex changes can get an independent review before execution starts.\n- Run `status` to see current progress, `doctor` to troubleshoot.\n\n### Verify Your Install\n\n```bash\npython3 scripts/sopify_status.py --format text\npython3 scripts/sopify_doctor.py --format text\n```\n\n- `will bootstrap on first project trigger`: the host install is ready and the project-local runtime has not been prepared yet\n- `workspace outcome: stub_selected [continue]`: the workspace runtime entry is healthy\n- Payload or bundle corruption errors (for example `global_bundle_missing`, `global_bundle_incompatible`, or `global_index_corrupted`): repair the install and retry\n\n### First Use\n\nAfter install, open your selected host inside a repository and paste one of the prompts below.\n\n```text\n# Simple task\n\"Fix the typo on line 42 in src/utils.ts\"\n\n# Medium task\n\"Add error handling to login, signup, and password reset\"\n\n# Complex task\n\"~go Add user authentication with JWT\"\n\n# Plan only\n\"~go plan Refactor the database layer\"\n```\n\n### What It Looks Like\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./assets/sopify-workflow.jpg\" width=\"800\" alt=\"Sopify Workflow — Start, Pause, Resume across hosts\" /\u003e\n\u003c/div\u003e\n\nThe workflow follows a start → pause → resume cycle. Sopify stops automatically when facts are missing or a decision needs confirmation, and picks up from the last checkpoint — even if you switch to a different AI host.\n\nFor the full workflow, checkpoints, and plan lifecycle details, see [How Sopify Works](./docs/how-sopify-works.en.md).\n\n## Configuration\n\nStart from the example config:\n\n```bash\ncp examples/sopify.config.yaml ./sopify.config.yaml\n```\n\nMost commonly used settings:\n\n```yaml\nbrand: auto\nlanguage: en-US\n\nworkflow:\n  mode: adaptive\n  require_score: 7\n\nplan:\n  directory: .sopify-skills\n```\n\nNotes:\n\n- `workflow.mode` supports `strict / adaptive / minimal`\n- `plan.directory` only affects newly created knowledge and plan directories\n\n## Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `~go` | Automatically route and run the full workflow |\n| `~go plan` | Plan only |\n| `~go exec` | Advanced restore/debug entry, not the default user path |\n| `~go finalize` | Close out the current metadata-managed plan |\n\nMost users only need `~go` and `~go plan`; maintainer validation commands live in [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Directory Structure\n\n```text\nsopify/\n├── scripts/               # install, diagnostics, and maintainer scripts\n├── examples/              # configuration examples\n├── docs/                  # workflow guides and developer references\n├── runtime/               # built-in runtime / skill packages\n├── skills/                # prompt-layer source of truth\n├── .sopify-skills/        # project knowledge base\n│   ├── blueprint/         # design baseline, reduction targets\n│   │   └── architecture-decision-records/  # ADR entity files\n│   ├── plan/              # active plans\n│   └── history/           # archived plans\n└── installer/             # host adapters and install orchestration\n```\n\nThis is a simplified view of the core layout. See [docs/how-sopify-works.en.md](./docs/how-sopify-works.en.md) for the full workflow, checkpoints, and knowledge layout.\n\n## FAQ\n\n### Q: How do I switch language?\n\nUpdate `sopify.config.yaml`:\n\n```yaml\nlanguage: zh-CN  # or en-US\n```\n\n### Q: Where are plan packages stored?\n\nBy default they live under `.sopify-skills/` in the project root. To change that:\n\n```yaml\nplan:\n  directory: .my-custom-dir\n```\n\nThis only affects newly created directories; existing history is not migrated automatically.\n\n### Q: When should I use `--workspace` prewarm?\n\nMost users do not need it. A default install is already complete; Sopify bootstraps the project-local runtime automatically on the first trigger.\n\nUse `--workspace` only for maintainer validation, CI, or when you explicitly want to prewarm a specific repository ahead of time. For this advanced path, use the repo-local installer:\n\n```bash\npython3 scripts/install_sopify.py --target codex:en-US --workspace /path/to/project\n```\n\n### Q: How do I reset learned preferences?\n\nDelete or clear `.sopify-skills/user/preferences.md`; keep `feedback.jsonl` only if you still want the audit trail.\n\n### Q: When should I run sync scripts?\n\nWhen you change `skills/{zh,en}` (source templates or skill packages), or `runtime/builtin_skill_packages/*/skill.yaml`, follow the validation steps in [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Version History\n\n- See [CHANGELOG.md](./CHANGELOG.md) for the detailed history\n\n## License\n\nThis repository uses dual licensing:\n\n- Code and config: Apache 2.0, see [LICENSE](./LICENSE)\n- Documentation: CC BY 4.0, see [LICENSE-docs](./LICENSE-docs)\n\n## Contributing\n\nFor user-visible behavior changes, update both `README.md` and `README.zh-CN.md` when needed, then follow [CONTRIBUTING.md](./CONTRIBUTING.md) for validation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevidentloop%2Fsopify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevidentloop%2Fsopify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevidentloop%2Fsopify/lists"}