Project truth stays with the project.
Skopos keeps durable knowledge in tracked, human-readable sources; compiles local working state separately; and explains approvals, checks, proof, and coordination limits instead of hiding them behind an agent summary.
.skopos/**Rebuildable working state01Tracked and reviewable
02Approval before material change
03Readiness with reasons
Tracked truth and local working state stay separate.
Your durable project knowledge remains reviewable and portable. Runtime machinery can be rebuilt without becoming another source of truth.
docs/architecture/How the system is shapeddocs/decisions/Why durable choices were madetools/skopos/Project-approved Actions and GuardsAGENTS.mdCanonical agent operating contract
Human-readable, reviewable in pull requests, and portable across supported agents.
.skopos/index/Rebuildable project projections.skopos/cache/Generated host adapters and caches.skopos/coordination.sqliteLive claims and Session state.skopos/runs/Action output and Evidence envelopes
May contain sensitive project details. Rebuildable state is not meant to be committed or shared wholesale.
Know what each stage may change.
Skopos makes the write boundary visible. Material restructuring and sensitive capabilities do not become authorized merely because an agent suggested them.
Learn the project before changing it.
Skopos inventories the repository and gives the coding agent a bounded brief for understanding current code, documentation, commands, and project truth.
Approve one coherent setup plan.
Skopos groups Memory, Scope, checks, rules, Skills, instructions, and host context into one review. Material changes wait for an explicit decision.
Keep intent and proof attached.
Skopos records Task state, decisions, claims, Actions, and Evidence. The coding agent still owns reasoning, implementation, and human-authored documentation changes.
Review durable impact before finishing.
A Task closes only after its acceptance has fresh proof and its Memory impact is explicitly resolved as updated or reviewed with no change.
Instructions guide. Guards decide.
Not every part of an agent workflow has the same strength. Skopos names the difference so guidance is never marketed as enforcement.
Instructions
Tell a participating agent how the project expects work to happen.
Guards
Require, prohibit, or demand approval and proof for a transition.
Actions
Expose exact project commands and integrations with declared inputs, effects, and safety.
Readiness
Reports ready, needs review, or blocked—with the exact reason and next safe step.
A green check expires when the work changes.
Evidence records the exact command, inputs, relevant source, configuration, environment, result, actor, and time. Change a declared dependency and the previous success becomes stale.
- Fresh proof covers the Task acceptance.
- Relevant source changes invalidate that proof.
- The focused check runs again against the new state.
T-7f3a91c2src/checkout/recovery.ts changed after the last passing run.
Coordination is visible—and cooperative.
Participating Sessions can claim bounded paths, detect overlap, record mutations, and surface unexplained changes. That is coordination, not a filesystem sandbox.
Skopos-aware Sessions
- One writing Task per Session
- Transactional overlapping-path checks
- Mutation and contamination audit
- Audited stale-ownership takeover
Unmediated processes
A script, editor, agent, or person that bypasses the coordination runtime can still change files. Skopos may detect the unexplained change and reduce Readiness; it cannot claim the write was prevented.
Capabilities are declared before execution.
Projects decide which commands and integrations are legitimate. Skopos checks the declared boundary before an Action runs and records only the proof needed to explain the result.
Local files
Current core state lives with the repository through the CLI and MCP runtime.
Network and browsers
An Action must declare these capabilities, and unavailable hosts stop before execution.
Secrets
Required secret names take part in preflight. Secret values never enter Action runs or Evidence.
External services
Mutations require declared external effects and a provider receipt. The receipt is not a universal sandbox or rollback guarantee.
Trust the explanation, not a badge alone.
Skopos helps coding agents follow your project. It does not replace the agent, upload a second source of truth, or describe cooperative guidance as hard security.
- 01Skopos does not replace the coding agent or make implementation decisions for it.
- 02Advisory instructions are not hard security boundaries.
- 03Cooperative claims cannot prevent an unmediated process from writing files.
- 04A passing Task does not automatically prove project integration or release readiness.
- 05Local .skopos data can contain project paths, snippets, prompts, screenshots, and receipts; keep it out of source control and do not upload it wholesale.
Give your agent clear authority—and clear limits.
Start with one repository. Keep durable truth reviewable, make sensitive capabilities explicit, and require proof that still matches the source.