Skip to content

getting-started.md

Latest commit

 

History

History
273 lines (197 loc) · 10.4 KB

getting-started.md

File metadata and controls

273 lines (197 loc) · 10.4 KB
Raw

Getting Started with Sopify

This guide walks through adding Sopify to an existing repository and using it with your preferred AI host.

Overview

Sopify adds resumable, traceable AI workflows to any project. After setup:

  • Work pauses automatically when facts are missing or a decision needs you
  • Work resumes from where it stopped — even on a different AI host
  • Plans, decisions, and reviews persist as reusable project assets

Requirements

  • Git repository (local or remote)
  • Python 3.11+
  • An AI host: Codex, Claude, Qoder, Copilot, or Cursor

Quick Setup (One Command)

From your project root:

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

This creates:

File Purpose
.sopify/sopify.json Workspace marker — tells the host that Sopify is active
.gitignore Managed block — excludes transient state from version control
.github/copilot-instructions.md Copilot entry — project-level instruction for Copilot

Skip Copilot files: Pass --no-copilot with --target copilot if you only want workspace markers.

Inspect-First Setup

Review the script before running:

curl -fsSL -o sopify-install.sh https://github.com/evidentloop/sopify/releases/latest/download/install.sh
less sopify-install.sh
bash sopify-install.sh --target copilot

Or clone and run the Python entry point directly:

git clone https://github.com/evidentloop/sopify.git /tmp/sopify
python3 /tmp/sopify/scripts/sopify_init.py init --workspace .

Optional EvidentLoop Companion

Sopify works without EvidentLoop. EvidentLoop turns a local Git diff into an interactive, feedback-ready HTML audit report. To install the current EvidentLoop CLI and Skill from their official sources, or reuse healthy existing components, opt in explicitly:

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

If you downloaded the installer for inspection, pass the same flag to bash sopify-install.sh.

The option is off by default and is not saved as a runtime setting. The CLI is a current-user uv tool; the Skill path depends on the target host:

Target EvidentLoop Skill path Scope
Codex $HOME/.agents/skills/evidentloop/ Current user
Claude $HOME/.claude/skills/evidentloop/ Current user
Qoder $HOME/.qoder/skills/evidentloop/ Current user
Copilot <workspace>/.github/skills/evidentloop/ Current project

These locations follow the host documentation for Codex, Claude Code, Qoder, and GitHub Copilot.

For new installs, Sopify follows EvidentLoop's current official commands: uv tool install evidentloop for the CLI and npx skills@latest add evidentloop/evidentloop --skill evidentloop for the Skill. Existing components are reused when the CLI doctor is healthy and the Skill front matter declares name: evidentloop; Sopify does not upgrade them or maintain an EvidentLoop compatibility matrix. uv is required only when the CLI is missing; Git and npx only when the Skill is missing.

Sopify is installed first and remains usable if the optional setup does not finish. Skill downloads happen in a temporary directory and are copied to the final host path only after validation, so a failed attempt does not leave a partial Skill there. Rerun the same command, or install EvidentLoop independently from its official repository.

After a fresh CLI install, the installer also checks that a future host can resolve evidentloop from PATH. If the uv tool directory is not visible yet, it leaves the validated CLI in place and asks you to run uv tool update-shell, restart the shell and AI host, then rerun the same command. It never edits your shell profile automatically.

For Copilot, pass --workspace <path> or run the installer from the target project. The installer writes only .github/skills/evidentloop/; it does not add a project .agents/skills/ copy or skills-lock.json. That is GitHub's documented project Skill location and becomes part of your project: review it, and commit it yourself if a cloud workflow needs it. Sopify does not commit or update it. A cloud-hosted agent also does not automatically receive the EvidentLoop CLI installed on your local machine. This option proves local component placement and health only; Skill discovery and audit E2E still require host evidence, and cloud CLI availability must be provisioned separately.

Host-Specific Setup

Codex / Claude

These hosts use a global prompt header. Install Sopify globally first, then bootstrap individual projects:

# Global install (one-time)
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target codex:en-US

# Workspace bootstrap (per project)
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target copilot

After install, use ~go in your AI host to start a managed workflow.

Copilot

Copilot discovers instructions via project-level files. The install command writes .github/copilot-instructions.md automatically.

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

Copilot reads project-level instruction files across its supported surfaces (VS Code Chat, Copilot CLI, Cloud Agent, Code Review — as of May 2025). Full trigger wiring (equivalent to Codex/Claude ~go) is coming in a future release.

Cursor IDE and local Agent CLI

One Cursor installation configures both local surfaces: the IDE gets a user-level Plugin Rule, while Agent CLI gets a top-level Skill for plan, development, resume, and closeout requests. Both share the phase Skills, payload under ~/.cursor/, and user Hooks in ~/.cursor/hooks.json:

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

After the first install or any local Plugin update, restart Cursor or run Developer: Reload Window before checking the Plugin and its Rule.

--workspace is not required and no project Rule or .sopify state is created during install. --with-evidentloop is not supported for Cursor in this release. The Plugin Rule uses valid .mdc frontmatter with alwaysApply: true and routes to ~/.cursor/skills/sopify.

Agent CLI does not load the user Plugin Rule by itself. For a Sopify workflow request, Cursor may select ~/.cursor/skills/sopify/SKILL.md; that entry reads the Rule before routing phase Skills. Ordinary questions do not have to use this path, and selection is not promised to behave identically across models. Cloud Agent remains outside this release. No launcher, project Rule, prompt injector, or runtime is added. See Cursor host acceptance. The tier remains BASELINE_SUPPORTED.

Verify Setup

Cursor installs at user scope and intentionally does not create a workspace marker. From the Sopify checkout, verify its install surface with:

python3 scripts/sopify_doctor.py --format json --home-root "$HOME"

After reloading Cursor, also confirm that the user-scope Sopify Plugin rule appears under Customize > Rules with mode Always. These checks prove installation and Plugin rule registration, not model behavior.

For a separately bootstrapped workspace, check its marker with:

cat .sopify/sopify.json

Expected output:

{
  "bundle_version": "2026-06-10.191940",
  "capabilities": [],
  "locator_mode": "global_first",
  "schema_version": "1",
  "workspace_kind": "external"
}

Using Sopify

Start a Task

Open your AI host in the project directory and describe what you want to do:

Fix the typo on line 42 in src/utils.ts

For managed workflows with planning and review:

~go Add user authentication with JWT

Commands

Note: These commands currently work in Codex and Claude. Copilot trigger wiring is coming in a future release — see Host-Specific Setup.

Command Description
~go Automatically route and run the full workflow
~go plan Plan only — analyze and produce a plan without executing
~go finalize Close out the current plan

Most users only need ~go.

Ordinary questions and small fixes are answered directly, even if local plan state is stale. Sopify reads the managed-plan chain only when you start, continue, or finalize managed work; any state write then goes through sopify_writer.

What Gets Created

As you work, Sopify creates project knowledge in .sopify/:

.sopify/
├── sopify.json       # workspace marker (from bootstrap)
├── project.md        # technical conventions (auto-created)
├── blueprint/        # design baseline and protocol spec
├── plan/             # active work packages + receipts
├── history/          # archived completed work + receipts
└── state/            # protocol state (git-ignored, 2 files only)
  • blueprint/, plan/, history/ are tracked by git — they are your project memory
  • state/ is git-ignored — it holds only active_plan.json (a pure plan_id pointer) and current_handoff.json (resume hint). If missing during a managed action, the host can browse plan/ for candidates without auto-resuming one during ordinary questions

Updating

Re-run the install command to update the workspace marker and instruction files:

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

The workspace bootstrap path is idempotent — it preserves existing settings and only updates what changed.

Removing Sopify

rm -rf .sopify/
rm -f .github/copilot-instructions.md

Then remove the # BEGIN sopify-managed / # END sopify-managed block from your .gitignore.

Further Reading