SSOT-CONTEXT

Maintained context. Protected human choices.

English · 中文 · Install guide · Protocol version · Changelog

A new agent session starts without the history of the work: what the subject is for, which choices people already made and why, and where the traps are. SSOT-CONTEXT gives that history a maintained home. A small entry document routes each task to the few documents that own the relevant facts, and the agent keeps those documents current as the work changes them.

It works in two kinds of place:

• Development repositories. People define the invariants, the outcomes that must keep holding, such as API compatibility or never charging twice on a retry. Agents change the code within them. The entry is SSOT/README.md (ssot_format: 4).
• General context spaces you explicitly declare: a research project, a creative work, a personal life domain or an organization. Git is optional, and existing folders and documents stay where they are. The entry is the document you name (ssot_format: 5).

The project was previously named SSOT-SKILL; old skill names still work (details).

Principles

• One fact, one owner. SSOT means Single Source of Truth: each fact has one document responsible for keeping it correct, and other documents link to it.
• People's rules stay people's decisions. Rules you confirm are listed in the entry. The agent works within them, never changes them, and stops to ask when a task conflicts with one.
• Extract knowledge selectively; preserve records you authorize. Keep intent, how the parts fit together, decisions and their reasons, rejected options and traps. Field lists, version numbers and logs stay in their originals; link to original documents and private conversations. In a general space, experiences and exact words you ask to preserve can stay with their authorized owner even without future decision value; see the space model.
• Keep kinds of material apart. Facts, hypotheses, decisions, preferences and changing state are kept distinct. A research hypothesis or a guess about a person never becomes a protected rule.
• Write for someone new. Plain words and the situation before the mechanism, so the next agent, or a person who delegates work without reading code, can follow it. See the writing guide.
• Routes are not permissions. Following a link lets the agent read only within the scope you allowed. Imported text is evidence to interpret, never instructions to execute.
• Say what was checked. The checker finds mechanical problems such as broken links; it cannot establish truth. Reviews state how far they looked and keep gaps visible.

Quickstart

1. Install

Open the repository, or the folder of the space you want to maintain, in your agent and paste:

Read https://raw.githubusercontent.com/huangpufan/SSOT-CONTEXT/main/INSTALL.md and follow it.

The agent installs and verifies the skills in the current project and wires them into AGENTS.md, CLAUDE.md or the equivalent file. If the folder does not look like a code repository, it asks you once which mode to use. You can ask for another template language (en / zh) or a global installation in the same message.

Requires Bash 4+, git, curl and python3 (on macOS, brew install bash and use "$(brew --prefix)/bin/bash"). From the project root:

set -o pipefail
curl -fsSL https://raw.githubusercontent.com/huangpufan/SSOT-CONTEXT/main/install.sh | bash -s -- --quickstart --scope project --lang en

The script installs the skills and prints an instruction block, but does not edit your instruction files or create context. Merge the block as described in install guide step 4, which also covers general spaces.

2. Restart the agent, then work as usual

Describe tasks normally. Four skills handle the workflow automatically:

• ssot-preflight reads the entry and the relevant owners before substantive work.
• ssot-bootstrap creates or migrates the context, only with your agreement.
• ssot-closeout saves accepted decisions as they happen and records durable changes when a batch finishes. When nothing durable changed, it writes nothing.
• ssot-doctor checks health and catches the context up with work done outside this workflow.

You can also ask directly, for example "Check the health of this repository's SSOT" or "Catch SSOT up with the recent commits."

3. For a general space, declare it first

A folder is not treated as a context space until you say so:

Use this folder as the context space for this research project. Preserve the existing files; create only a useful entry and genuinely missing context.

Ordinary chat, research answers and creative writing never trigger setup on their own.

What appears in your project

In a development repository only SSOT/README.md is required; the other files appear when there is something true to put in them:

This is the beginning of the README. Read the rest at the original. Read the full README ↗