Get one repository ready for coding agents.
Start Skopos from npm, let it guide your agent one decision at a time, and finish with project truth that can guide the next Session.
01Choose
02Start
03Clarify
04Review
05Verify
Choose the project you are bringing.
The safe setup path depends on whether the repository already contains project truth.
Bring the project you already have.
Skopos first learns the repository boundary and preserves current truth. Material documentation changes stay inside one review before anything is applied.
“Set up Skopos in this repository with the npm package @unisane/skopos@latest: https://www.npmjs.com/package/@unisane/skopos. Run `npm exec --package @unisane/skopos@latest -- skopos setup . --actor <stable-id> --json`. This is an existing project, so preserve the project truth already in the repository. Follow Skopos’s returned guidance one decision at a time. Stop whenever it asks for my input, and apply only the recommendations I approve.”
npm exec --package @unisane/skopos@latest -- skopos setup . --actor <stable-id> --json
- The repository root and inferred project boundary
- Generated project instructions, config, and ignore rules, plus any docs-router change proposed for your approval
- Observed facts versus assumptions and contradictions
- Any proposed material documentation change before approval
Review before broad agent work.
Setup does not declare every detected fact correct. Inspect the consolidated review, adjust real project choices, and apply only what matches the repository.
- 01Boundary
Confirm the repository root, project mode, Scopes, and Memory roots.
- 02Truth
Separate observed files and commands from inferences and open assumptions.
- 03Changes
Review AGENTS.md, configuration, docs routing, and ignore rules before committing.
- 04Approval
Require an exact accepted recommendation before material documentation restructuring.
Return without replaying the old chat.
Once the project is set up, a new Session can recover the active work, relevant Memory, remaining proof, and next safe action from the repository.
npm exec --package @unisane/skopos@latest -- skopos session context . --actor <stable-id> --jsonnpm exec --package @unisane/skopos@latest -- skopos work next . --actor <stable-id> --json
“Continue the current Skopos Task. Load the latest intent, decisions, relevant Project Memory, remaining checks, and handoff. Before editing, tell me what is already done, what remains, and the next safe action.”
You are done when the project can explain itself.
Setup success is observable. It is not just the absence of a CLI error.
- 01The generated tracked files match the repository you intend to govern.
- 02Local .skopos/** state is excluded from source control.
- 03Setup reports either setup-ready status or one specific question, recommendation, or verification step.
- 04Your coding agent can explain the current project boundary and next safe action without replaying the setup conversation.
If setup does not look right, stop safely.
Skopos should make the recovery path explicit instead of encouraging you to force a questionable setup through.
Skopos selected the wrong boundary
Stop and rerun from the actual repository root. A nested package should be a separate Skopos project only when it has its own explicit configuration and Memory root.
Existing documentation conflicts
Do not overwrite it. Run setup review, compare the conflicting sources, and approve only the exact material changes you want.
The host did not load context automatically
Run session context manually and give its compact result to the agent. Host automation depth is documented separately from core support.
The CLI is not available globally
Use npm exec with @unisane/skopos@latest, as shown in this guide.
Next, use Skopos on one real feature.
Let the agent recover the relevant project context, clarify the outcome, bind the work, and prove it against the checks your project owns.