Synesis

Shared team knowledge for AI coding agents.

Synesis (Greek: σύνεσις — understanding, the faculty of putting things together) is a file-based, repo-embedded, agent-agnostic shared knowledge protocol for software teams.

---

Why this exists

AI coding agents are becoming essential infrastructure, but every vendor wants to own your team's knowledge. Claude has its memory system. Copilot has its knowledge bases. Each one locks your conventions, decisions, and institutional memory inside a proprietary format that only works with that vendor's tools.

Switch agents and you start from zero. Run multiple agents and you maintain parallel knowledge stores. Your team's understanding of itself becomes a vendor dependency.

Synesis exists to prevent that. Plain markdown in a git repo. Any agent that can read a file — Claude Code, Codex, Copilot, Gemini, or whatever ships next quarter — inherits your team's knowledge automatically. No migration, no export, no lock-in.

The problem it solves

Your team makes decisions every week. Conventions exist as tribal knowledge. New developers ask the same questions. AI coding agents start every session with zero context about how your team works.

Documentation wikis go stale. Onboarding docs drift from reality. The knowledge that matters most — why things are the way they are — lives in people's heads and gets lost when they leave.

The solution

Markdown files in a git repo. No server, no database, no API keys, no SaaS. Clone and go.

Synesis gives your team a shared vault of decisions, conventions, people profiles, and institutional memory. Every AI coding agent that can read a file inherits your team's knowledge automatically — who owns what, how you do things, what was already decided and why.

What it is not

• Not a SaaS product — it's files in your repo
• Not an MCP server — no runtime, no process
• Not an npm package — nothing to install
• Not a database — git is the database

Quick start

1. Click "Use this template" to create your team's vault
2. Clone it locally
3. Open it in your AI coding agent (Claude Code, Codex, Copilot — all supported)
4. Say hello — the agent reads the protocol and offers to onboard you

That's it. The agent now knows the protocol. As you add people, decisions, and conventions, every agent session inherits that knowledge.

What lives in the vault

synesis/
  PROTOCOL.md              # the protocol — teaches any agent the conventions
  CLAUDE.md                # Claude Code shim → PROTOCOL.md
  AGENTS.md                # Codex shim → PROTOCOL.md
  .github/
    copilot-instructions.md  # Copilot shim → PROTOCOL.md
  skills/                  # agent capabilities (onboard, decide, lint, etc.)
  records/                 # decisions and institutional memory
  people/                  # one profile per team member
  conventions/             # how your team does things
  attachments/             # binary files linked to records
  tools/                   # team-shared scripts
  synesis.code-workspace   # template multi-root workspace
  .gitignore               # ignores .obsidian/ (per-user config)

Records

Decisions, ADRs, and anything the team agreed on. Each record captures what was decided, why, who decided, and who was consulted. Records can be marked superseded and linked to their replacement.

---
title: Auth provider decision
date: 2026-08-18
decided-by: [SC, MK]
consulted: [JL]
last-verified: 2026-08-18
status: active
superseded-by:
tags: [auth, architecture]
---

## Context

We needed a managed auth provider for the SaaS launch. Rolling our own
was ruled out — too much surface area for a two-person team.

## Options considered

- **Auth0** — mature, expensive at scale, complex dashboard
- **Clerk** — modern DX, good Next.js integration, newer company
- **Supabase Auth** — free tier, already using Supabase for DB

## Decision

Clerk. Best DX for our stack (Next.js + React), and the pricing model
scales linearly. [[people/sarah]] evaluated all three over a week.

## Consequences

- Auth UI components come from Clerk's React SDK
- Session tokens are JWTs — middleware validates on every request
- Follow-up: migrate the existing email/password prototype by EOW

People

One markdown file per team member. Role, expertise, ownership areas. The agent uses these to answer "who should I ask about X?" and to detect new team members automatically via git config user.email.

---
name: Sarah Chen
initials: SC
aliases: [SC, Sarah]
email: sarah.chen@company.com
role: Frontend developer
joined: 2026-08-18
tags: [frontend, auth]
---

## Expertise

- React, Next.js, TypeScript
- Auth flows and session management
- Accessibility (WCAG 2.1 AA)

## Owns

- Auth UI (login, signup, password reset)
- Dashboard components
- Design system tokens

Conventions

Your team's standards as markdown files. Git branching strategy, commit message format, coding standards, deployment process — all in one place, readable by both humans and agents. New devs and new agents get the same briefing.

---
name: Git branching strategy
last-verified: 2026-08-18
tags: [git, workflow]
---

All work happens on feature branches off `main`. Branch naming:
`feat/short-description`, `fix/short-description`, `chore/short-description`.

PRs require one approval before merge. Squash merge to keep `main` linear.
Delete the branch after merge — no long-lived branches except `main`.

Hotfixes branch directly from `main` and merge back with a regular PR.
No cherry-picking between branches.

Supported harnesses

Synesis works with any AI coding agent that can read project files. It ships one-line shim files for three harnesses out of the box:

Harness	Mode	Shim file
Claude Code	CLI + VS Code	CLAUDE.md
OpenAI Codex	CLI + VS Code	AGENTS.md
GitHub Copilot	CLI + VS Code	.github/copilot-instructions.md

Each shim redirects the agent into PROTOCOL.md, where the actual protocol lives. Adding support for a new harness = adding a one-line shim file. The knowledge stays in one place.

Verbs and skills

Verbs are commands you give to the agent. Each verb maps to a skill file in skills/. The agent reads skill frontmatter to discover what's available — no separate verb index to maintain.

Skills are markdown files that define triggers and step-by-step instructions. See skills/ for the full set.

VS Code multi-root workspace

For VS Code users, open your Synesis vault alongside your project repos in a multi-root workspace:

{
  "folders": [
    { "path": "../synesis" },
    { "path": "../my-project" },
    { "path": "../another-project" }
  ]
}

The agent sees both your code and your team knowledge. When it needs context — conventions, ownership, past decisions — the vault is right there in the workspace.

All three supported harnesses (Claude Code, Codex, Copilot) auto-discover their shim files from workspace folders. A template .code-workspace file is included.

Scope boundary: Vault conventions apply to the vault only. In a multi-root workspace, project repos keep their own rules. The agent never applies vault conventions (branching, commit style, merge strategy) to a project repo unless that project's own instructions say to.

Onboarding

When a new developer clones the vault and says hello, the agent:

1. Reads git config user.email and checks people/ for a match
2. If no match — runs the onboard skill: a lightweight interview (name, initials, role, areas of work)
3. Creates their profile in people/, commits and pushes it
4. Delivers a full team briefing: conventions, recent decisions, who owns what

The next time they say hello, they skip straight to the briefing. No setup docs to read. No Confluence pages to find.

Knowledge freshness

Records and conventions carry a last-verified date. The lint skill flags anything older than the configurable threshold (default: 90 days). No automated deletion — just visibility. The team decides what to update, verify, or supersede.

Obsidian-compatible

The vault doubles as an Obsidian vault. [[wikilinks]] for internal cross-references, aliases and tags in frontmatter for filtering and linking. .obsidian/ is gitignored so each user keeps their own Obsidian config.

Design principles

1. Files, not services. Markdown in a repo. No server, no runtime, no API keys.
2. Agent-agnostic. Works with any harness that reads project files. No vendor lock-in.
3. Brand-neutral internals. PROTOCOL.md, not SYNESIS.md. The brand lives here in the README, never in the protocol files.
4. Trust the team. No PR gates. Anyone can commit. Git history is the audit trail.
5. Fork and own. Use the template, make it yours. The protocol defines the structure; your team fills it with real knowledge.
6. Obsidian-compatible. Wikilinks, tags, aliases — the vault works in Obsidian out of the box.

Contributing

No PR gate on your team vault. Commit directly. Trust the team. git blame + git log = full audit trail. The lint skill handles hygiene.

For contributions to the Synesis protocol itself (this template repo), PRs welcome.

License

MIT