Reasoning stays where it happened.
- Local plans and specs are scattered.
- Decisions survive in commits or chat.
- Another agent cannot see what was decided.
- Several files may claim the same fact.
Setup outcome / inspected locally
Version control for AI agent reasoning
Paste one line. Your agent reads the code, Markdown, bounded Git history, and Syns repositories you can already access; proposes the knowledge structure this project needs; shows every source and move for approval; compares it with what you have; then publishes only what you approve.
Syns hosts the reasoning that produces code. GitHub hosts the code.
Send to your coding agent
Plain-text hosted skill
Read and follow https://syns-setup.pages.dev/SKILL.md to set up or join the Syns repository for this project.
● No source upload · no account before review · nothing changes without approval.
Input 01
Current code + Markdown
manifests · schemas · docs · tests
Input 02
Bounded Git history
co-change · decisions · topology
Input 03
Accessible Syns repositories
join · extend · derive · link
Input 04
Six pinned reference shapes
or an honest zero-match
understandreuseproposecompare
Proposed repository
Review required
STRUCTURE.md ← read first
AGENTS.md ← routing
architecture/
boundaries.md [code:41]
decisions/
product/
constraints.md [docs:18]
work/
current.md [history]
retrospectives/
1 owner / fact · source lineageverified path
Gate A · awaiting you
read order declared
old → proposed mapping
source project unchanged
Before / after
The outcome is a repository your agents can actually follow.
Not another folder dropped into the codebase. A separately versioned, agent-readable corpus with its authority and sources made explicit.
A separate home for deliberate artifacts.
- Every agent starts from a declared read order.
- Each fact has one canonical owner.
- Claims carry source lineage.
- History, revert, collaborators, and team access ship with the repository.
What it reads
Evidence first. Structure second.
The setup agent runs because you invoked it in your local checkout. It narrows from project entry points to the sources needed to verify a claim.
Code and Markdown
Entry points, manifests, schemas, tests, instructions, specs, plans, and native stores.
Bounded Git evidence
Recurring areas, co-changing files, project topology, and historical decision language.
Repositories you can access
Existing Syns repositories are checked for a closer source of truth before another is proposed.
Six pinned shapes
Ticks, Linear, Notion, Attio, Spec Kit, and OpenSpec — Syns-authored and internally checked.
What the command does
A bounded path from inspection to handoff.
Setup is a sequence of inspectable operations. Evaluation and publication remain separate decisions.
Understands the work.
Reads local code and Markdown, then uses bounded Git history to understand what exists, what changes together, and where durable intent currently lives.
Checks what already exists.
Looks at accessible Syns repositories and chooses join, extend, derive, link, consolidate, or ignore rather than duplicating by default.
Compares all six reference shapes.
Considers ticks, Linear, Notion, Attio, Spec Kit, and OpenSpec. At most one branded base is used; a neutral zero-match is valid.
Asks only material questions.
At most three source-of-truth questions, only when the files cannot answer and the answer changes ownership or structure. Blank means unknown, never approval.
Opens the structure review.
Shows the full tree, every source and move, old-to-proposed mapping, unknowns, reuse decisions, and evaluation plan. Approval stages it only in an isolated private area.
Runs matched read-only tasks.
After Gate A approval, fresh agents compare the immutable current package with the staged proposal under matched conditions. Results open in a second review.
Adopts only named operations.
Local adoption, a project adapter, private publication, collaborators, and team access are separate approvals. The default destination is separate; the old package remains available.
Returns the exact handoff.
After a successful private publication, it can add approved access and returns the owner/name plus the exact sentence the next person gives their agent.
The two gates
Review is not permission to publish.
Approval is bound to the exact proposal or operation. Silence and blank controls approve nothing.
Structure review
Permits only isolated staging and a read-only evaluation against the current package.
- Materialize the exact proposal privately
- Validate paths, sources, and links
- Run sealed, read-only comparison tasks
Does not edit the project · does not create a remote repository
Evaluation decision + exact operations
The second review reveals the comparison, then asks separately what — if anything — may change.
- Adopt into a separate local destination
- Add a marker-delimited project adapter
- Publish the accepted tree privately
- Add named collaborators and exact roles
- Create or select a team, invite people, and grant access
Each operation is unchecked by default · the old package remains available
Team handoff
One identity. Explicit access. A reproducible join.
The owner gets a private repository identity. Collaborators or a team get named roles. The next person joins into an empty directory.
Private repository
The accepted corpus is published as owner/name, then verified before access changes begin.
Exact roles
Direct collaborators receive read, write, or admin. Team members and repository access are approved separately.
Join, do not redesign
In an empty directory, the next person gives their agent:
Run syns-init and join `owner/name` in an empty directory. Use the repository's declared read order; do not redesign it.
Truthful sync condition: after a successful push and a subsequent successful pull, the next agent reads the committed update.
The Claude Code integration can pull at session start and push at lifecycle stop when installed. Pi support is available. Setup detects integrations; it does not promise or install hooks.
Boundary map
What Syns owns — and what stays where it is.
Adoption does not require replacing your code host, tracker, editor, or agent. It gives the deliberate reasoning its own lifecycle.
- Specifications and plans
- Architecture decisions and constraints
- Configurations and operating instructions
- Retrospectives and durable work state
- Version history, revert, roles, and team access
- Source code — keep GitHub or your existing code host
- Tickets — keep Linear, Jira, or your tracker
- Transcripts and prompts — they record the route, not the accepted decision
- Live collaborative documents and chat
- Private source-repository access
An instruction file is routing. The repository is the corpus it routes agents to.
FAQ / sharp edges
The questions to ask before you paste.
Direct answers, including the cases where Git and a good instruction file may already be enough.
Does it upload my code?
No. Syns cannot see your private source-code repositories. Your invoked setup agent reads the local checkout to prepare evidence. Only the separately approved reasoning repository is published.
Will it overwrite my existing docs?
Not before explicit, exact approval. The proposal and evaluation happen in an isolated private area. The default accepted destination is separate, and the old package remains available. An in-place migration requires a complete move/change/delete manifest, backup, and reversal approval.
Does it invent a template?
No. It mines current evidence, checks accessible existing Syns repositories, and compares six pinned reference shapes. It can reuse, extend, derive, link, or propose consolidation; an honest zero-match is valid. The shelf is Syns-authored and internally checked, not customer-proven.
Can I add the team during setup?
Yes — after successful private publication. The evaluation review can separately approve direct collaborators, exact access roles, a team, pending email invites, and the team-to-repository role. Nothing is preselected.
Is synchronization real time?
No. The lifecycle is push, then pull. When an installed integration completes a push and the next agent subsequently pulls, that agent reads the committed update. A stale push is rejected rather than silently overwriting newer remote work; the agent can then pull, read, adjust, and try again.
Why not use Git?
For one developer, one agent, and a short-lived project, Git plus a good instruction file can be enough — keep it. Reasoning changes at a different cadence from code and needs distribution across teammates and sandboxes without adding every plan revision to source history. Syns is the separate host for that corpus; Git remains the host for code.
Start with a review, not a migration
Let the evidence draw the map.
Inspect and propose locally without an account. Nothing reaches a private remote — and nothing in the source project changes — until the exact operation is approved.
Copy the complete instruction
No truncation
Read and follow https://syns-setup.pages.dev/SKILL.md to set up or join the Syns repository for this project.