# specgit — full LLM context > Curated Markdown of specgit's highest-authority public pages for single-fetch ingestion. Short index: https://specgit.com/llms.txt. Individual pages are also available as Markdown via content negotiation. Company: Fn First Holdings LLC. Product category: GitHub-native documentation collaboration. GitHub remains the source of truth; Zero Content Retention — specgit never keeps a copy of documents or comments. ## Source: https://specgit.com/ # specgit — GitHub-native docs collaboration Write specs in a visual editor while engineers review them as pull requests. Zero Content Retention — we never keep a copy of your docs. ## Why keep docs in the repo Docs go stale when they live away from the code. Today: the spec lives in a doc app, the code lives in GitHub, engineers get a link in Slack, read it once, and build from the ticket — the product moves on and the doc describes a product that no longer exists. With specgit: the spec lives in the repo next to the code it describes, engineers review it as a pull request (same flow, same tools, same habits), every update is a commit, every discussion is on the record, and the doc sits exactly where engineers and AI coding agents already look. ## Features - **Visual editor** — Write and format docs without learning Markdown or Git. - **Inline comments** — Highlight text to start review conversations. - **Live collaboration** — Edit together in real time. - **GitHub-native** — GitHub remains the durable source of truth; reviews are real pull requests. - **Required approvals, end to end** — When a repo's rules require an approving review, specgit shows exactly what's needed ("needs 2 approving reviews — 1 so far"), lets the author ask a teammate for review from the publish menu, and lets the reviewer approve or ask for changes right in specgit. "Publish when approved" publishes automatically the moment approval lands. Works with GitHub branch protection and repository rulesets. - **Full history** — Every change is a commit; undo back to any point. - **Clean formats** — Markdown and HTML stay untouched in the repo, usable by any other tool. - **Obsidian-flavored Markdown** — Wiki links, embeds, callouts (any kind, titles, folding), ==highlights==, footnotes, LaTeX math (KaTeX), frontmatter, task lists, and rendered Mermaid diagrams; unrecognized syntax is preserved byte-for-byte on save. - **Starter templates** — Create new docs from starters (product spec, backlog tracker, decision record, meeting notes, agent instructions) or start blank. - **Upload Markdown or HTML** — Drop in `.md`, `.markdown`, `.html`, or `.htm` and save them into your repo as-is. - **Import existing docs** — Convert Word (.docx), PowerPoint (.pptx), Excel (.xlsx), and PDF files to Markdown (via Microsoft's MarkItDown) and save them into your repo. - **specgit AI co-editor** — Agent chat (edits the document with the user), Review (reads the document and posts inline comment threads), Triage (works through open comments and proposes resolutions), all available by text or voice; every proposal requires human approval. - **View changes** — Word-style redlines of the working draft against main, with change navigation and selective undo. - **Merge conflicts** — Early warning when main has moved, plus in-editor resolution (keep mine / theirs / both / custom) and an optional AI-prefilled resolution reviewed by the user. - **Continue working** — The repo file list surfaces every unpublished draft — including never-published new docs — for one-click resume. - **Dialect convert** — Explicit GFM ↔ Obsidian conversion with a preview diff; a `specgit-dialect` frontmatter flag travels with the file. - **Cross-branch awareness** — File-list badges and an in-editor bar flag in-flight edits to the same doc on other branches, with side-by-side compare and one-tap switch. - **Read-only browsing and Copy to** — Docs in repos without write access open read-only, with one click to copy the doc (images included) into a writable repo. - **Images in Markdown** — Paste or drop images into a doc; they are stored as doc-relative, content-hashed files in the repo and preview natively on GitHub. ## Getting started - **Everyone signs in through the specgit GitHub App** — fine-grained, repo-by-repo permissions with short-lived tokens; no separate password, no broad OAuth grant. - **Individuals** — Sign in with GitHub at https://specgit.com/ and pick the repositories to grant. - **Teams and enterprises** — An org admin installs the App once, limited to selected repositories; members can request the installation in one click. - **Complete repo list, easy switching** — The repo list shows every repository your installations can reach — including org repos you access through team membership — and you can switch GitHub accounts from the header menu. - Try the real editor on a sample doc at https://specgit.com/try — no account required. ## Privacy - **Zero Content Retention** — specgit never keeps a copy of your documents or comments — GitHub remains the source of truth. - Temporary live-collaboration state is deleted after publish or direct commit and after at most 7 days of inactivity. - specgit uses content-free product analytics to improve the product — analytics never receive documents, comments, prompts, selections, chat, audio, repo names, filenames, paths, raw URLs, or input text. Outside the EEA, UK, and Switzerland, public measurement is cookieless and unidentified; signed-in events are pseudonymous and can be opted out. In those regions — or when region is unknown — nothing is sent before separate, informed, revocable opt-in. No ad tech, sale, or retargeting. See the Privacy Policy for the processor, retention, and controls. - Sign in through GitHub directly; specgit never sees your password. ## Pricing - **Free** — $0. Unlimited collaborators on 1 repository, 5 publishes/month, plus 1 AI Review and 1 AI Triage run per month. No credit card required. - **Pro** — $8/seat/month. Unlimited repositories and publishing; full AI co-editor pay-as-you-go with a one-time $10 AI credit your first month and 3 AI Review + 3 AI Triage runs included monthly. - **Pro Plus** — $16/seat/month. Pro plus $10/month of AI usage included per seat and 10% off on-demand AI rates. - **FreshSpec** — account add-ons for autonomous doc freshness (contact for early access): 1 repo / 5 docs, 5 repos / 25 docs, 20 repos / 100 docs, or Custom. - **Enterprise** — custom quote for large teams (volume discounts, invoicing, priority onboarding). - Per-seat, billed via Stripe; annual billing saves 20%. Details: [Pricing](https://specgit.com/pricing). ## Guides & writing - [The specgit blog](https://specgit.com/blog) — writing on product specs and docs that live in the repo, including [why product specs go stale](https://specgit.com/blog/why-product-specs-go-stale) and [Notion vs GitHub for product specs](https://specgit.com/blog/notion-vs-github-for-product-specs). - [Google Docs alternative for product specs](https://specgit.com/google-docs-alternative-product-specs) - [Docs as code for product managers](https://specgit.com/docs-as-code-for-product-managers) - [Obsidian + GitHub collaboration](https://specgit.com/obsidian-github-collaboration) ## Links - [Pricing](https://specgit.com/pricing) - [How specgit works — architecture](https://specgit.com/how-it-works) - [Support](https://specgit.com/support) - [Security and data privacy](https://specgit.com/security) - [Privacy Policy](https://specgit.com/privacy) - [Terms of Use](https://specgit.com/terms) - [LLM index](https://specgit.com/llms.txt) - [Agent auth guide](https://specgit.com/auth.md) - [specgit developer resources](https://specgit.com/developers) ## FAQ ### What is specgit? specgit is a GitHub-native docs collaboration app for teams that keep specs, docs, and decisions in GitHub. ### Does specgit store my documents? No. GitHub remains the source of truth — specgit never keeps a copy of your documents or comments. Live collaboration uses temporary editing state that is deleted after publish or direct commit, or after up to 7 inactive days. User-invoked AI processing and explicitly shared AI feedback are described in the Privacy Policy. ### How do the AI features handle my documents? AI features are optional and only run when a user invokes them. When a user explicitly invokes an AI action, the document text (and its review comments, for review and triage) is sent to specgit's AI model provider to generate the response; voice sessions stream audio for the session's duration. specgit keeps none of that content — only usage metadata (tokens, model, cost) for metering and the usage dashboard, plus anonymous accepted/dismissed proposal totals. The one exception is explicit consent: if you tick "share this conversation" when rating an AI response, that transcript is kept for up to 90 days and used only to diagnose and improve the AI. Content is never used to train models, and every AI-proposed change requires human approval before it is applied or posted. ### Who is specgit for? PMs who work closely with engineers — and the designers and product leaders who write alongside them. You write the spec in the repo, engineers review it like any other change, and nobody has to learn Git or Markdown. ### How does signing in to specgit work? All sign-in goes through the specgit GitHub App: fine-grained, least-privilege permissions and short-lived tokens, limited to the repositories granted to the installation. Individuals install it on their account; org admins install it once for the organization (members can request it in one click). There is no separate password. ### Can I import existing Word documents? Yes. Upload a Word (.docx), PowerPoint (.pptx), Excel (.xlsx), or PDF file and specgit converts it to Markdown using Microsoft's open-source MarkItDown converter, then saves it into your repository. The uploaded file is discarded immediately after conversion; only the Markdown you save is committed. ### Does specgit work with Obsidian-flavored Markdown? Yes. The editor understands wiki links ([[Page]] and aliases), embeds (![[file]]), callouts of any kind (with custom titles and fold markers), ==highlights==, footnotes, LaTeX math rendered with KaTeX, YAML frontmatter, task lists, and Mermaid diagrams rendered inline. Syntax the editor doesn't model is preserved byte-for-byte on save, so a vault synced to GitHub stays clean in Obsidian too. ### What if my repo requires an approving review before changes go live? specgit handles required reviews end to end. When a repo's rules require approval, the editor says exactly what's needed — "needs 2 approving reviews, 1 so far" — instead of failing mysteriously. The author asks a teammate for review from the publish menu; the reviewer approves (or asks for changes) directly in specgit, attributed to their own GitHub account, and self-approval is prevented just like on GitHub. "Publish when approved" publishes the document automatically the moment approval lands. Works with GitHub branch protection and repository rulesets. --- ## Source: https://specgit.com/pricing # Pricing — specgit Simple per-seat pricing. Every plan keeps GitHub as the source of truth. ## Plans ### Free — $0 Run one real project with your whole team, free. - Unlimited collaborators — comments, drafts, and live editing for your whole team - 1 repository - 5 publishes to your repo per month - Visual editor, inline comments, live collaboration - GitHub-native pull request reviews - Try the AI: 1 AI Review and 1 AI Triage run per month ### Pro — $8/seat/month (or $6.40/seat/month billed annually) For teams that live in their docs. - Unlimited repositories - Unlimited published documents - Seats cover editors only — unlimited free viewers & commenters - Buy once for your whole org — seats are used automatically as people edit - Full AI co-editor, pay-as-you-go — includes a one-time $10 AI credit your first month - 3 AI Review and 3 AI Triage runs included every month - Priority email support — target response within 1 business day ### Pro Plus — $16/seat/month (or $12.80/seat/month billed annually) Pro, plus AI usage included every month. - Everything in Pro - $10/month of AI usage included per seat - 10% off on-demand AI usage rates - AI agent, review, triage, and voice sessions in the editor - Transparent per-token pricing and a full usage dashboard ### FreshSpec add-ons — contact for early access Autonomous doc freshness by monitored repo and maintained doc capacity. - FreshSpec 1 — $39/month, 1 repo / 5 docs - FreshSpec 5 — $99/month, 5 repos / 25 docs - FreshSpec 20 — $249/month, 20 repos / 100 docs - FreshSpec Custom — contact sales ### Enterprise — custom quote For large teams: volume seat discounts, invoicing and procurement support, security review assistance, and priority onboarding. Built for teams whose security review asks where the data lives: GitHub remains the source of truth, specgit never keeps a copy of your documents or comments, and your content is never used to train AI models. [Contact us](https://specgit.com/support?subject=Enterprise+%2F+Sales). ## Billing - Plans belong to the account (user or org) that owns the repositories, never to individual people. Free accounts are limited by usage (repos/publishes, shared); paid accounts are metered by editor seats instead. The two never stack. - Per-seat pricing in USD; payments processed by Stripe. - Seats count EDITORS only: a seat is used the first time someone edits a doc in the account's repositories each month. Viewing and commenting are always free and never use a seat. - Organizations: any admin (verified against GitHub) can buy for the org from Settings → Billing; one subscription covers everyone editing in the org's repositories. One subscription can mix Pro seats and Pro Plus seats. - Pro Plus seats are assigned to named GitHub users by an admin in billing settings; a personal Pro Plus subscription travels with the user into any repo. - AI usage is metered in dollars at published rates: $2.40 per 1M input tokens, $0.60 per 1M cached input tokens, $7.20 per 1M output tokens (2x above 200K context), and $0.06/minute for voice. Pro Plus pays 10% less on on-demand usage. Beyond included allowances, on-demand usage is off by default until an account admin enables it and sets a monthly limit; it is billed in arrears. Requests are throttled to 10/minute per person, and a full usage dashboard shows every AI event with CSV export. - Seat growth is automatic (auto-true-up, on by default): active editors are never cut off, and a new editor beyond purchased seats adds a prorated seat to the subscription automatically. Admins can opt out in billing settings (new editors beyond the cap are then blocked until seats are added). - Annual billing: Pro $76.80/seat/year, Pro Plus $153.60/seat/year — 20% off monthly. - A "publish" is a document reaching the base branch (merged review or direct commit). - Cancel anytime; the account moves to Free. GitHub remains the source of truth, and specgit never keeps a copy of your documents or comments. [Pricing page](https://specgit.com/pricing) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/security # Security and data privacy — specgit specgit is built around Zero Content Retention: specgit never keeps a copy of your documents or comments — GitHub remains the source of truth. ## The short version - Zero Content Retention: we never keep a copy of your documents or comments. GitHub remains the source of truth — the only things that ever touch our servers are temporary: live-collaboration state while you edit together, AI processing you explicitly invoke, and feedback you explicitly choose to share. - Product analytics are content-free and processed by PostHog Cloud EU; regional choices, retention, access, and deletion are detailed in Privacy. - No ad tech, retargeting, enrichment brokers, sale of information, or content analytics. - Your content is never used to train AI models; the optional specgit AI runs only when you invoke it, and every AI change requires your approval. - Sign-in is a fine-grained GitHub App — repo-by-repo grants, short-lived tokens, no separate password. These fall out of the architecture, documented at [How specgit works](https://specgit.com/how-it-works). ## Does specgit store my documents? No. specgit reads documents from GitHub when you open them and saves edits back through commits, branches, pull requests, and comments. Where docs are held is also a product question, not just a security one — the approaches are compared in [Notion vs GitHub for product specs](https://specgit.com/blog/notion-vs-github-for-product-specs). ## What happens during live collaboration? Live collaboration uses temporary realtime state. That state is deleted after publish or direct commit, and inactive rooms are swept after up to 7 days. ## How does specgit use product analytics? specgit uses content-free product analytics processed by PostHog Cloud EU. Outside the EEA, UK, and Switzerland, public measurement is cookieless and unidentified; signed-in events are pseudonymous and can be opted out. In those regions — or when region is unknown — nothing is sent before separate, informed, revocable opt-in. Analytics never receive documents, comments, prompts, selections, chat, audio, repo names, filenames, paths, raw URLs, or input text. No ad tech, sale, or retargeting. See the Privacy Policy for retention and controls. ## How does GitHub sign-in work? You sign in through GitHub directly via the specgit GitHub App. specgit never sees your GitHub password and there is no separate specgit password. GitHub access is used only for actions you request. ## What access does the specgit GitHub App have? The App installation requests four fine-grained repository permissions, only on the repositories granted to it. GitHub handles user authorization separately: signing in identifies the person using specgit but does not install the App or change repository access. Access is revocable anytime from GitHub settings. ### Installation permissions - **Contents (Read & write)** — Read the Markdown and HTML files people open, and save their edits back as ordinary git commits on review branches. - **Pull requests (Read & write)** — Open a pull request for each draft, post review comments, and merge when someone publishes. - **Issues (Read & write)** — Post and read the discussion comments on those pull requests (GitHub serves PR-level comments through its issues API). - **Metadata (Read-only)** — List the repositories the installation grants — the mandatory baseline permission for every GitHub App. ### The installation cannot - change repository settings, branch protections, or webhooks - manage collaborators, teams, deploy keys, or invitations - reach any repository outside the ones the installation grants - move the durable document or review record out of GitHub; GitHub remains the source of truth ## How do the AI features handle my documents? The AI features (the in-editor AI assistant, AI review comments, comment triage, and voice) are optional and only run when you invoke them. When you explicitly start an AI action, the document text (and its review comments, for review and triage) is sent to our AI model provider to generate the response; voice sessions stream conversation audio for the duration of the session. specgit keeps none of that content in routine AI usage records—only usage metadata (token counts, model, cost, and timestamps) plus anonymous accepted/dismissed proposal totals. The one exception is explicit consent: if you tick "share this conversation" when rating an AI response, that transcript is kept for up to 90 days and used only to diagnose and improve the AI. Nothing is sent for AI processing in the background or without an explicit request, your content is not used to train models, and every AI-proposed change requires your approval before it is applied or posted. Our AI model provider is xAI. specgit's xAI account has Zero Data Retention enabled: API inputs and outputs are processed to generate the response and are not persisted by xAI — the default 30-day abuse-monitoring retention does not apply, and voice conversation history is not retained. API inputs and outputs are never used to train xAI's models. ## What we never retain - Your documents and comments — specgit never keeps a copy and runs no document database. Temporary collaboration state and explicitly shared AI feedback have the bounded retention described below. - Your GitHub password or credentials — sign-in happens on GitHub directly. - Document content in AI usage records — metadata only (token counts, model, cost, timestamps); AI quality counters are anonymous daily totals with no account, document, or content attached. - AI chat history on our servers — it stays on your device. ## What we retain (and for how long) - Temporary realtime editing state — deleted after publish or direct commit; inactive rooms are swept after up to 7 days. - GitHub access tokens — stored server-side for active sessions only, encrypted at rest (AES-256-GCM), deleted on sign-out or after 30 days of inactivity. - Account preferences (theme, editor layout, AI auto-approve) and terms-of-use acceptance — stored with your GitHub identity; settings only, never document content. - Operational logs — retained for up to 30 days. - Raw product analytics events are retained for no more than 12 months; aggregate statistics may remain longer. - AI usage metadata — token counts, model, cost, and timestamps for metering and the usage dashboard. - AI feedback — ratings, optional notes, and explicitly shared conversation transcripts — retained for up to 90 days, then deleted. ## Evaluating specgit for your company? specgit is built for teams whose security review asks where the data lives: GitHub remains the source of truth, specgit never keeps a copy of your documents or comments, and your content is never used to train AI models. [Contact us](https://specgit.com/support?subject=Security+review) and we'll answer your security questionnaire directly. [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/how-it-works # How specgit works — architecture specgit is deliberately thin: a visual editor and a review workflow layered on primitives GitHub already provides. There is no document database — saves are commits, comments are pull request threads, publish is a merge. ## The flow 1. **Your browser — the visual editor.** Each open document is a live collaborative document: edits, teammates' cursors, and inline comments merge conflict-free in real time. 2. **Real-time collaboration service — temporary co-editing state.** A real-time collaboration service relays edits between everyone in the doc. Its state is a working buffer only: deleted after publish or direct commit, swept after up to 7 days of inactivity. 3. **specgit server — the GitHub broker.** Authenticates users through the specgit GitHub App, verifies repo access before minting any realtime token, and translates editor actions into commits, branches, pull requests, and merges. It never keeps a copy of your documents or comments. 4. **Your GitHub repository — the only source of truth.** Documents, comments, review history, and approvals live here as plain Markdown/HTML files, commits, and pull requests — readable by every other tool, engineer, and AI coding agent. ## Step 1 — Access: a fine-grained GitHub App, repo by repo All sign-in goes through the specgit GitHub App — no separate password, no broad OAuth grant. Users (or an org admin) choose exactly which repositories the installation can reach; tokens are short-lived. The App requests four narrow permissions: - **Contents (Read & write)** — Read the Markdown and HTML files people open, and save their edits back as ordinary git commits on review branches. - **Pull requests (Read & write)** — Open a pull request for each draft, post review comments, and merge when someone publishes. - **Issues (Read & write)** — Post and read the discussion comments on those pull requests (GitHub serves PR-level comments through its issues API). - **Metadata (Read-only)** — List the repositories the installation grants — the mandatory baseline permission for every GitHub App. The installation cannot: - change repository settings, branch protections, or webhooks - manage collaborators, teams, deploy keys, or invitations - reach any repository outside the ones the installation grants - move the durable document or review record out of GitHub; GitHub remains the source of truth ## Step 2 — Live co-editing: conflict-free, in real time Open documents load into a live collaborative document built for conflict-free live editing — any number of people can edit simultaneously without overwriting each other — synced by a real-time collaboration service. Room access is brokered: the specgit server verifies with the user's own GitHub token that they can access the repository, then mints a short-lived client token for a room whose id is derived server-side from the verified document reference. Clients can never request a token for an arbitrary room, and the browser never holds the realtime server's secret. Realtime state is temporary working state on our servers: deleted after publish or direct commit, and inactive rooms are swept after up to 7 days. ## Step 3 — Persistence: everything becomes a GitHub primitive - **Save** → a git commit on a review branch, attributed to the person who made it. - **Comment** → a pull request review thread. - **Ask for review / approve** → a pull request review that counts toward branch protection and required-review rules. - **Publish** → a merge to the base branch; "Publish when approved" arms GitHub auto-merge. Renames are true git renames, so history follows the file. ## What this architecture limits by design - specgit never keeps a copy of your documents or comments — GitHub remains the source of truth. - Product analytics are content-free and processed by PostHog Cloud EU. Restricted or unknown regions send nothing before separate opt-in; elsewhere public events are cookieless and unidentified and signed-in events are pseudonymous with opt-out. No ad tech, sale, or retargeting. See Privacy for retention and rights. - Your content is never used to train AI models. The optional specgit AI runs only when invoked, and every AI-proposed change requires human approval. - Server logs are metadata only — timings, ids, and counts, never document text. [Security and data privacy](https://specgit.com/security) | [For your IT admin](https://specgit.com/for-your-admin) | [Pricing](https://specgit.com/pricing) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/for-your-admin # Approving specgit for your organization — a brief for IT admins Someone on your team asked to use specgit — a visual editor that saves Markdown and HTML into your GitHub repositories. Saves are commits, comments are pull request review threads, and publishing is a merge. ## What you're approving A GitHub App installation on your organization, limited to the repositories you select. Members sign in with their own GitHub accounts, so every edit and comment is attributed to the person who made it — no separate accounts or passwords. Change the repository grant or uninstall anytime from your organization's GitHub settings; access is revoked immediately. ## The exact permissions, and why - **Contents (Read & write)** — Read the Markdown and HTML files people open, and save their edits back as ordinary git commits on review branches. - **Pull requests (Read & write)** — Open a pull request for each draft, post review comments, and merge when someone publishes. - **Issues (Read & write)** — Post and read the discussion comments on those pull requests (GitHub serves PR-level comments through its issues API). - **Metadata (Read-only)** — List the repositories the installation grants — the mandatory baseline permission for every GitHub App. The installation cannot: - change repository settings, branch protections, or webhooks - manage collaborators, teams, deploy keys, or invitations - reach any repository outside the ones the installation grants - move the durable document or review record out of GitHub; GitHub remains the source of truth ## Where your data lives - specgit never keeps a copy of your documents or comments — GitHub remains the source of truth. - Access tokens are short-lived, stored encrypted for active sessions only, and revoked at GitHub on sign-out. - Product analytics are content-free and processed by PostHog Cloud EU. Restricted or unknown regions send nothing before separate opt-in; elsewhere public events are cookieless and unidentified and signed-in events are pseudonymous with opt-out. No ad tech, sale, or retargeting. See Privacy for retention and rights. - Operational logs are metadata only, never document content, and are retained for up to 30 days. - The optional AI features run only when a user invokes them, every AI-proposed change requires human approval, and content is never used to train models. ## How to approve the request Member requests appear under your organization's **Settings → Third-party access → GitHub Apps**, and GitHub emails organization owners when a member requests an App. Approving lets you choose exactly which repositories the installation can reach. [Security and data privacy](https://specgit.com/security) | [Privacy Policy](https://specgit.com/privacy) | [Terms of Use](https://specgit.com/terms) | [Support](https://specgit.com/support) --- ## Source: https://specgit.com/developers # specgit developer resources specgit is GitHub-native docs collaboration, not a generic REST platform. Agents read public facts as Markdown, then use the review tools after a GitHub App sign-in. There are no self-serve API keys. ## When to use specgit Use specgit when the job is editing, commenting on, or publishing Markdown or HTML that already lives in a GitHub repository — or when a product team needs a visual editor whose saves are commits, comments are pull request review threads, and publish is a merge. Do not use specgit as a model API, a webhook hub, or a substitute for GitHub's own REST or GraphQL APIs. ## Quickstart 1. Read https://specgit.com/llms.txt. 2. Open the no-account sandbox at https://specgit.com/try. 3. Sign in through the GitHub App (https://specgit.com/auth.md). The session cookie is the credential. 4. Call `GET https://specgit.com/api/agent/tools` or POST JSON-RPC `initialize` to `/api/agent`. ## Public surfaces - [LLM index](https://specgit.com/llms.txt): Product facts, pricing, and when-to-use guidance. Prefer this over scraping HTML. - [Full LLM context](https://specgit.com/llms-full.txt): One-file Markdown of the highest-authority public pages. - [OpenAPI](https://specgit.com/openapi.json): Typed agent API for document review tools, including problem+json errors. - [Agent auth](https://specgit.com/auth.md): GitHub App sign-in. specgit has no API keys and no password. A session cookie is the credential. - [MCP server](https://specgit.com/api/agent): Streamable HTTP MCP at /api/agent. Discover the card at /.well-known/mcp.json. tools/call needs the session cookie. - [Sandbox](https://specgit.com/try): The real editor on a sample document. No account required. ## Authentication Everyone signs in through the specgit GitHub App. After the callback, the browser (or agent) holds a session cookie for `GET /api/agent/tools`, `POST /api/agent/invoke`, and MCP `tools/call`. [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/google-docs-alternative-product-specs # A Google Docs–style editor for product specs that live in GitHub Google Docs is great at writing — and terrible at staying true to a shipping product. specgit gives PMs the same easy visual editing, but the document itself is a file in your GitHub repository: saves are commits, comments are pull request threads, and publishing is a merge. The spec lives next to the code it describes. ## Why Google Docs fails for specs The spec lives in Drive, the code lives in GitHub, and the two drift apart from day one. Engineers get a link in Slack, read it once, and build from the ticket; the product moves on and the doc quietly describes a product that no longer exists. Docs keeps resolved comments in the doc's comment history and keeps a version history, but nothing holds the document until the engineer who owns that area signs off, and sharing is managed in a permissions system your engineering org doesn't control. Meanwhile, AI coding agents working in the repo can't see the doc at all. The full mechanism is written up in [why product specs go stale](https://specgit.com/blog/why-product-specs-go-stale). ## Saves are commits Every save in specgit is a real Git commit, attributed to the person who made it: full history, exact diffs, and undo back to any point — the same audit trail engineers already trust for code. ## Comments are pull request threads Highlight text and comment, just like in Docs — but the thread is a real GitHub pull request review conversation. Engineers reply from GitHub or from specgit, and every discussion stays on the record next to the change it's about. ## Publishing is a merge Publishing merges the spec to your base branch — the flow engineers use to ship code. Branch protection and required reviews work end to end: specgit shows exactly what's needed ("needs 2 approving reviews — 1 so far"), reviewers approve in specgit, and "Publish when approved" publishes automatically the moment approval lands. ## Zero Content Retention Zero Content Retention: we never keep a copy of your documents or comments. GitHub remains the source of truth — the only things that ever touch our servers are temporary: live-collaboration state while you edit together, AI processing you explicitly invoke, and feedback you explicitly choose to share. Files stay plain Markdown or HTML, usable by any other tool. If you stop using specgit, the durable record is already in your repository. ## Content-free analytics, no ad tech Product analytics are content-free and processed by PostHog Cloud EU. Restricted or unknown regions send nothing before separate opt-in; elsewhere public events are cookieless and unidentified and signed-in events are pseudonymous with opt-out. No ad tech, sale, or retargeting. See Privacy for retention and rights. Sign-in goes through the specgit GitHub App with fine-grained, repo-by-repo permissions and short-lived tokens — no separate password, no broad OAuth grant. ## FAQ ### Is specgit a full replacement for Google Docs? For product specs and docs that should live with the code, yes — the same easy visual editing plus real engineering review. For everything else in your Drive (offer letters, spreadsheets, slide decks), keep using Docs. ### Do PMs need to learn Git or Markdown? No. specgit is a visual editor; commits, branches, and pull requests happen behind the scenes. ### Can I move my existing Google Docs into specgit? Yes. Download a Google Doc as Word (.docx) and upload it — specgit converts it to Markdown (via Microsoft's open-source MarkItDown) and saves it into your repository. PowerPoint, Excel, and PDF convert the same way. ### Does specgit store my documents on its servers? No. GitHub remains the source of truth — specgit never keeps a copy of your documents or comments. Live collaboration uses temporary editing state that is deleted after publish or direct commit, or after up to 7 inactive days. User-invoked AI processing and explicitly shared AI feedback are described in the Privacy Policy. ### Is there a free plan? Yes: unlimited collaborators on 1 repository with 5 publishes per month, no credit card required. Related: [Docs as code for product managers](https://specgit.com/docs-as-code-for-product-managers) | [Obsidian + GitHub collaboration](https://specgit.com/obsidian-github-collaboration) | [The specgit blog](https://specgit.com/blog) | [Pricing](https://specgit.com/pricing) | [Security](https://specgit.com/security) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/docs-as-code-for-product-managers # Docs as code, without asking PMs to learn Git Engineering teams adopted docs as code because it works: docs live in the repo, change through review, and stay current with the product. The only thing stopping product teams from joining is the tooling — Git, Markdown, and pull request mechanics. specgit removes exactly that barrier. ## What docs-as-code means for product The repo is where product truth lives — the code, the reviews, and increasingly the AI agents that write code all work there. Docs as code puts the documents that shape the product's future in the same place as the code that defines its present: specs are plain Markdown files in the repository, every change has an author and a timestamp, and review happens in the open. ## Why Notion and Google Docs break the loop A spec in Notion or Docs starts drifting the moment engineering picks up the work. Engineers read it once, build from the ticket, and never come back; changes made during implementation never flow into the doc; six months later the spec describes a product that no longer exists — in an app with its own permissions, search, and graveyard of stale pages. On the blog: [why specs go stale](https://specgit.com/blog/why-product-specs-go-stale) and a fair [Notion vs GitHub comparison](https://specgit.com/blog/notion-vs-github-for-product-specs). ## Shared-drive UX on the repo specgit makes a GitHub repository feel like a shared drive: browse files, open a doc, write in a visual editor with a formatting toolbar, inline comments, and live co-editing. Behind the scenes every save is a commit and drafts are real branches. Markdown and HTML upload as-is; Word, PowerPoint, Excel, and PDF import by conversion to clean Markdown. ## Review like a pull request Inline comments are pull request threads; approvals count toward branch protection and required-review rules; publishing merges the doc to your base branch. specgit shows exactly what's blocking a publish and can publish automatically the moment required approvals land. ## AI agents read the same files AI coding agents work in the repository — that's where they look for context. A spec next to the code is context they use automatically; a spec in a separate app is invisible. specgit also includes an optional AI co-editor, specgit AI, working on those same files; every proposed change requires human approval. ## Getting started Sign in with GitHub through the specgit GitHub App — fine-grained, repo-by-repo permissions, no separate password. Open any Markdown or HTML doc in your repository or create one from a starter template. Free plan, no credit card; you can try the real editor on a sample doc at https://specgit.com/try without an account. ## FAQ ### What is docs as code? Treating documentation like source code: docs are plain-text files in a version-controlled repository, changed through the same review workflow as code — real history, real review, no separate permissions silo. ### Doesn't docs as code require learning Git? Traditionally yes — which is why it rarely sticks for product teams. specgit removes that requirement: PMs write in a browser-based visual editor and specgit handles commits, branches, and pull requests behind the scenes. ### How do engineers review a spec written in specgit? As a pull request — the exact flow they already use. Reviews work from GitHub or from specgit; branch protection and required reviews are honored end to end. ### What do AI coding agents get out of this? Repo-based agents read the files in the repository, so specs stored next to the code become context automatically — no integrations, no copy-paste. ### What does it cost to try? Nothing: the Free plan covers unlimited collaborators on 1 repository with 5 publishes per month, no credit card required. Related: [Google Docs alternative for product specs](https://specgit.com/google-docs-alternative-product-specs) | [Obsidian + GitHub collaboration](https://specgit.com/obsidian-github-collaboration) | [The specgit blog](https://specgit.com/blog) | [Pricing](https://specgit.com/pricing) | [Security](https://specgit.com/security) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/obsidian-github-collaboration # Collaborate on Obsidian-flavored Markdown in GitHub — with real review Your vault already lives in a Git repository (or could). specgit is the collaboration layer on top: teammates edit the same notes in a visual editor in the browser, comments become pull request threads, and publishing is a merge — while your Obsidian syntax survives untouched. specgit does not replace the Obsidian app; keep writing in Obsidian. ## Sync is not collaboration Obsidian Sync replicates a vault across your devices, and a shared vault extends that to as many as 20 collaborators who each hold their own Sync subscription; the community Git plugin commits your vault to a repo. Both solve replication, not teamwork. There's no way for a teammate to propose a change for review, no comment threads on a paragraph, and no approval before an edit lands. ## Wiki links, callouts, and embeds preserved specgit's editor understands Obsidian-flavored Markdown: wiki links ([[Page]] and aliases), embeds (![[file]]), callouts of any kind with custom titles and fold markers, ==highlights==, footnotes, LaTeX math rendered with KaTeX, YAML frontmatter, task lists, and Mermaid diagrams rendered inline. Syntax the editor doesn't model is preserved byte-for-byte on save, so files opened later in Obsidian look exactly as you left them. ## Comments are pull request threads Highlight a passage and comment — the discussion is a real GitHub pull request review thread, attributed to each person's own GitHub account, attached to the exact change it's about. ## Publish by merge Drafts are branches; publishing merges them. Branch protection and required reviews work end to end, "Publish when approved" merges automatically the moment approval lands, and if the base branch moved while you wrote, specgit warns early and offers in-editor conflict resolution. ## Your vault stays yours Notes stay plain Markdown files in your GitHub repository — readable by Obsidian and every other tool. Zero Content Retention: we never keep a copy of your documents or comments. GitHub remains the source of truth — the only things that ever touch our servers are temporary: live-collaboration state while you edit together, AI processing you explicitly invoke, and feedback you explicitly choose to share. Product analytics are content-free and processed by PostHog Cloud EU. Restricted or unknown regions send nothing before separate opt-in; elsewhere public events are cookieless and unidentified and signed-in events are pseudonymous with opt-out. No ad tech, sale, or retargeting. See Privacy for retention and rights. ## FAQ ### Does specgit replace Obsidian? No. Keep writing in Obsidian — specgit is the team collaboration layer on the repo that backs your vault. Teammates who don't use Obsidian edit the same notes in the browser. ### Will specgit mangle my Obsidian syntax? No. Recognized syntax is edited visually; anything the editor doesn't model is preserved byte-for-byte on save. ### How is this different from Obsidian Sync or the Git plugin? Sync replicates files between your own devices — no shared review, comments, or approvals. The Git plugin commits your vault but every collaborator needs Git set up. specgit works on the repo itself: browser editing, PR-thread comments, and in-editor merge conflict resolution. ### Where do my notes live? No. GitHub remains the source of truth — specgit never keeps a copy of your documents or comments. Live collaboration uses temporary editing state that is deleted after publish or direct commit, or after up to 7 inactive days. User-invoked AI processing and explicitly shared AI feedback are described in the Privacy Policy. ### What does it cost? Free to start: unlimited collaborators on 1 repository with 5 publishes per month, no credit card. Related: [Google Docs alternative for product specs](https://specgit.com/google-docs-alternative-product-specs) | [Docs as code for product managers](https://specgit.com/docs-as-code-for-product-managers) | [The specgit blog](https://specgit.com/blog) | [Pricing](https://specgit.com/pricing) | [Security](https://specgit.com/security) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/notion-alternatives # Notion alternatives for team docs and product specs (2026) *Published 2026-08-02 · Updated 2026-08-16* The best Notion alternative depends on where you need the documents to sit. If your team uses GitHub, put the documents in the repository and stop maintaining a second copy somewhere else — specs, handbooks, meeting notes, runbooks. [specgit](https://specgit.com/) is built for exactly that: it makes a GitHub repo behave like a shared drive, where saves are commits, comments are pull request review threads, and publish is a merge, so a PM writes in a visual editor and engineers review the result in the pull request queue they already work in. An empty repository is a fine place to start. Confluence still wins on Jira-native permissions and enterprise admin. Google Docs is still the fastest way to draft something and collect comments from people outside the team. Coda covers the part of Notion that acts like a database. Obsidian with a Git remote, GitBook, Anytype, and AppFlowy are other ways to hold the files yourselves. This guide compares those options for docs, specs, and knowledge bases. It does not try to replace Notion's drag-and-drop boards or its relational database views, which is a different search. ## Start by deciding where the documents should live Notion does four jobs at once: documents, a wiki, databases, and light project tracking. Very little else does all four, so replacing it starts with naming the part you actually use. If most of your pages are specs, requirements, decision records, and runbooks, you are shopping for a docs tool, and the question is which system owns the file. That answer decides the rest. A tool that keeps documents in its own cloud gives you an editor and comment threads. A tool backed by Git gives you version history, branches, and code review, at the cost of needing a repository. The table sorts the options along that split. *Notion and its main alternatives for team documentation, compared on review model and where the files are stored.* | Tool | Best for | Review model | Where docs live | Free tier | | --- | --- | --- | --- | --- | | **specgit** | Product and engineering teams whose docs belong next to the code | Pull request review threads, approvals, branch protection | Markdown and HTML files in your GitHub repo | Yes: 1 repo, 5 publishes a month, unlimited collaborators | | Notion (baseline) | All-in-one workspace: docs, wiki, databases, light project tracking | Inline comments and suggestions | Notion's cloud workspace | Yes, with a 1,000-block cap once a workspace has more than one member | | Confluence | Company-wide wiki, especially alongside Jira | Inline comments; page approvals through apps | Atlassian Cloud or Data Center | Yes, up to 10 users and 2 GB of storage | | Google Docs | Fast drafting and comments with people outside the team | Suggesting mode and comment threads | Google Drive | Yes, with a Google account | | Coda | Documents that behave like small internal applications | Comments; no formal approval step | Coda's cloud | Yes, with limits; billing counts doc makers, not viewers | | Slite | A narrow team knowledge base with search and doc verification | Comments and verification workflows | Slite's cloud | No permanent free plan; 14-day trial | | Outline | Self-hosted wiki for teams with someone to run it | Comments and page revisions | Your own server, or Outline's managed cloud | Free to self-host (BSL 1.1); the cloud version is paid | | Obsidian + Git | Individuals and small teams who want plain files | Whatever your Git host offers, handled manually | Local Markdown files, synced through a Git remote | Yes, the app is free to use, including at work | | GitBook | Published product documentation | Change requests and reviews | GitBook, with optional Git Sync to GitHub or GitLab | Yes for individuals; a Community plan for qualifying open source projects | | Anytype | Local-first, encrypted notes for one person or a small group | Comments; no pull request style review | Encrypted local storage, synced through the Anytype network or your own node | Yes | | AppFlowy | Open-source workspace with Notion's shape, including databases | Comments; no pull request style review | AppFlowy Cloud, or your own server | Yes, with limits; the self-hosted free tier is single user | ## specgit: docs in the GitHub repo, edited like a normal document specgit is a GitHub-native docs collaboration app. You pick a repo — empty is fine — and write in a visual editor. Start from a template, upload Markdown or HTML, import Word or PDF, or open a file that is already there. Saving writes a commit to a branch. Inline comments arrive as pull request review threads under the commenter's own GitHub identity. Publishing is a merge. A PM who has never opened a terminal can do all of that without learning Git or Markdown, which is the point of [docs as code for product managers](https://specgit.com/docs-as-code-for-product-managers). It is the pick here for any team that already reviews code in GitHub, and the review is the reason more than the editor is. A publish opens a real pull request, so a doc change inherits every rule the repo already enforces: required approving reviews, branch protection and rulesets, reviewer assignment, per-line comment threads, an attributed history nobody can quietly rewrite, and whatever CI the repo runs. specgit tells the author what is blocking a publish, such as "needs 2 approving reviews, 1 so far", and reviewers approve or request changes without leaving the editor. There is a redline View changes diff of the draft against main with selective undo, merge conflict resolution in the editor, and live co-editing. Because the file stays a file, every other tool that reads the repo can read the spec too, including the coding agents your engineers run, which is why repo-backed specs [drift less](https://specgit.com/blog/why-product-specs-go-stale). specgit never keeps a copy of your documents or comments. Sign-in goes through a GitHub App with fine-grained, repo-by-repo permissions and short-lived tokens instead of a broad OAuth grant. The narrow exceptions, covering live-collaboration state and AI that a person invokes, are written out on [security](https://specgit.com/security) and in [how specgit works](https://specgit.com/how-it-works). The free tier covers one repository and five publishes a month with unlimited collaborators, since commenting and drafting never consume a seat. [Pricing](https://specgit.com/pricing) has the rest, and you can [try the editor](https://specgit.com/try) before signing in. The honest limitation is narrower than people expect. Linked, wiki-style navigation is here already, since Obsidian wiki links and embeds work and the repo's folder tree is the page tree. Tracking works in text too: a backlog tracker is one of the starter templates, alongside a product spec, a decision record, meeting notes, and agent instructions, and task lists and Markdown tables carry the rest. What Markdown cannot give you is a Notion database as an application: filtered and sorted views, rollups, relations between tables, and a board you drag cards across. Lean on that and you should keep Notion, or something like it, for that piece. If the thing you call a database is a tracker, a table, or a set of linked pages, the repo does the job, and unlike a page in a vendor workspace it is readable by the coding agents your engineers run without anyone pasting it in. A save lands in a GitHub repository, so a team with no GitHub account is outside the product. A team that already uses GitHub does not need a second wiki for handbooks or meeting notes. The longer version of that tradeoff is in [Notion versus GitHub for product specs](https://specgit.com/blog/notion-vs-github-for-product-specs). ## Confluence, Coda, and Google Docs Confluence is Atlassian's wiki and the default at companies already running Jira, where a page links to an issue and permissions follow groups that exist. Its permission model and admin controls are more mature than anything else on this page. The free plan is capped at 10 users and 2 GB of storage, per [Atlassian's pricing page](https://www.atlassian.com/software/confluence/pricing). Its weakness is the wiki graveyard: pages accumulate, nothing expires, search returns four versions of the same document, and none sit anywhere near the code. Coda is the closest replacement for Notion's database half. Documents hold formulas, buttons, and automations, so a doc can work like a small internal application, and billing counts doc makers rather than every reader, which suits a small ops team building something for a large audience. The cost is the learning curve and the lock-in: a doc built on Coda formulas does not export into anything else in a useful shape, and for a plain product spec it is more machinery than the job needs. Google Docs is still the fastest way to write a first draft and collect comments from people outside the company, and suggesting mode beats most review interfaces. The problem for specs is distance. The doc sits in Drive, the code sits in a repo, nothing connects them, and the doc goes stale inside a quarter while coding agents never see it. That case is covered in the [Google Docs alternative for product specs](https://specgit.com/google-docs-alternative-product-specs). ## Slite and Outline Slite is a team knowledge base rather than an all-in-one workspace, and it is narrower than Notion on purpose: a clean editor, a folder structure, search that works, and verification workflows that flag documents nobody has confirmed lately. Teams tend to land there after a Notion workspace grew too big to search. Two caveats. Slite has no permanent free plan; [its pricing page](https://slite.com/pricing) lists a 14-day trial and paid tiers. It also does not do databases or project management. Outline is an open-source wiki you can run yourself. The editor is fast, content is stored as Markdown, and self-hosting is free under the Business Source License 1.1, which converts to Apache 2.0 after four years. Running it means PostgreSQL, Redis, and S3-compatible storage, and the managed cloud version is paid with no free tier. BSL is source-available rather than OSI-approved open source, which matters if your legal team draws that line. ## Obsidian, GitBook, Anytype, and AppFlowy Obsidian keeps everything as plain Markdown files in a folder on your machine, the app is free to use including at work, and the community Git plugin commits the vault to a remote, which buys you history and a backup for nothing. What it does not buy you is collaboration. The base app has no multiplayer editing, and review is whatever your Git host provides, which in practice means the least technical writer ends up resolving a merge conflict in a terminal. Adding team editing and pull request review on top of a repo-backed vault is covered in [Obsidian and GitHub collaboration](https://specgit.com/obsidian-github-collaboration). GitBook is built for published product documentation. It has a good editor, change requests for review, and Git Sync that mirrors content to a GitHub or GitLab repository, so writers get a UI and engineers get files. Its free plan covers a single user, and qualifying open source projects can apply for a Community plan. Paid pricing is charged per published site plus per user, a sensible shape for a docs site and an awkward one for internal specs. Point-by-point differences are in [specgit versus GitBook](https://specgit.com/specgit-vs-gitbook). Anytype is a local-first workspace. Content is stored on your device and encrypted before it syncs, the protocols are MIT licensed, and the applications ship under a source-available license. It is a real option if you would rather no vendor held your notes. It is weakest where team docs need the most strength: no review flow worth the name, and an object graph that takes longer to learn than a folder of files. AppFlowy is the closest open-source copy of Notion's shape, with documents, databases, and boards, running either on AppFlowy Cloud or on your own server. Check the licensing before planning a rollout. The self-hosted free tier is single user, and multi-user collaboration on your own infrastructure needs a commercial license, per the [AppFlowy Cloud repository](https://github.com/AppFlowy-IO/AppFlowy-Cloud). ## Getting your content out of Notion Notion exports to Markdown, HTML, and CSV from workspace settings. Pages come out as a folder tree, databases as CSV files, and internal links point at file names with a hash appended, so cleanup is real work. Budget time in proportion to how many databases you built, not how many pages you wrote. For a docs-first destination, the Markdown export is the useful one. Commit that folder to a GitHub repository and you have a starting point any editor, script, or coding agent can read. specgit also imports Word, PowerPoint, Excel, and PDF files by converting them to Markdown, which picks up older material that never made it into Notion. Once the folder is in the repo, specgit is what keeps non-engineers writing in it: starter templates, a visual editor over the files, and review that happens in the pull request instead of a second approval system somebody has to configure. For a product team that ships software, that is where we think the docs belong. If most of your writers are not engineers, the practical concerns are in [docs as code with non-technical contributors](https://specgit.com/docs-as-code-with-non-technical-contributors). ## Frequently asked questions ### What is the best free Notion alternative? The strongest free options either run on your own server or lean on something you already pay for. Outline is free to self-host if you can run PostgreSQL, Redis, and object storage. Google Docs is free with a Google account. Confluence's free plan is capped at 10 users and 2 GB of storage. specgit's free tier covers one repository and five publishes a month with unlimited collaborators, because commenting and drafting never consume a seat. Notion's own free plan stays generous for one person, but a 1,000-block cap applies once a second member joins, per [Notion's help center](https://www.notion.com/help/understanding-block-usage). ### What's the best Notion alternative for engineering teams? If the docs describe software your team is building, keep them in the repository the software lives in, and use [specgit](https://specgit.com/) to make that bearable for the people who are not engineers: a visual editor over the Markdown and HTML files in GitHub, where saves are commits, comments are pull request review threads, and publish is a merge, so a spec passes the same approvals, branch protection, and CI as the code. That inherited review is the argument. Confluence is the better answer if your organization runs Jira and needs enterprise permissions. Outline suits teams that want a self-hosted wiki and have someone to operate it. GitBook fits when you want a public documentation site rendered and hosted for you rather than built by your own pipeline. ### Can I move my docs out of Notion? Yes. Notion exports a workspace or an individual page to Markdown, HTML, or CSV, and databases come out as CSV files. Expect cleanup: nested pages become nested folders, file names carry a trailing hash, and internal links point at those file names rather than at your new tool's URLs. Plain pages survive well, and databases with views, rollups, and relations do not. A common path is to export to Markdown, commit the folder to a GitHub repository, and fix links there, which leaves the content in a format every other tool can read. ### Is there an open-source Notion alternative? AppFlowy is the closest match in shape, with documents, databases, and boards, though its self-hosted free tier is single user and multi-user collaboration needs a commercial license. Anytype publishes its protocols under MIT and its applications under a source-available license. Outline is source-available under the Business Source License 1.1, which converts to Apache 2.0 after four years. Obsidian is worth naming because people assume it belongs: the app is free to use, but it is not open source. Check each license yourself, since source-available and OSI-approved are not the same thing. ### What should product managers use instead of Notion for product specs? Use whatever puts the spec in the same place as the code it describes. When the spec lives in Notion, engineers read a copy, the copy drifts, and coding agents never see it. [specgit](https://specgit.com/) gives PMs a visual editor on the Markdown and HTML files in a GitHub repo, so a save is a commit and a review comment is a pull request thread, with no Git or Markdown knowledge required. Google Docs is still fine for early drafting. The full argument is in [docs as code for product managers](https://specgit.com/docs-as-code-for-product-managers). ### Do I need to know Git or Markdown to use a repo-backed docs tool? It depends which one. Obsidian with the Git plugin expects you to understand commits, remotes, and what to do when a sync conflicts, which rules it out for most non-engineers. specgit is built so that you do not: you sign in with GitHub, pick a repository, and edit in a visual editor, while the branch, commit, pull request, and merge happen underneath. Reviewers approve or request changes inside the editor under their own GitHub identity. That gap is covered in [docs as code with non-technical contributors](https://specgit.com/docs-as-code-with-non-technical-contributors). ### Which Notion alternative works best with AI coding agents? Coding agents read repositories. A spec stored in a vendor cloud is invisible to them unless someone pastes it in, so the repo-backed options have a structural advantage: specgit, GitBook with Git Sync, and Obsidian with a Git remote all leave the document as a file an agent can open. specgit adds review to that arrangement, so a change an agent suggests still lands as a pull request a human approves. It also has in-editor AI for co-editing, review comments, and comment triage, which runs only when someone invokes it. [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/specgit-vs-gitbook # specgit vs GitBook *Published 2026-08-02 · Updated 2026-08-16* Pick GitBook if you want the documentation website hosted for you without running a pipeline: a public product manual, an API guide, a help center with search on a custom domain. That is the job GitBook was built for and it is good at it. Pick specgit if your docs are internal specs and engineering documentation that should stay as plain files in your own repository. Publishing from specgit is a merge to the base branch, so a repo that already builds a site on merge keeps shipping that site while the writing and the review move into a visual editor. Both tools connect to GitHub, so neither choice means giving up Git. The difference is where the canonical copy sits and who signs off on a change. GitBook is a hosted platform that can mirror content two ways with a repo through Git Sync. specgit reads and writes the repo directly and keeps no copy. Sign-off is where we think the gap is widest: GitBook implements review inside GitBook, while specgit runs a doc change through the pull request machinery your engineering org already configured, so required approvals, branch protection, rulesets, and repo CI apply to a spec the way they apply to code. The sections below run the same criteria through both. ## Where the content lives In GitBook you author inside a GitBook space. Turn on Git Sync and that space mirrors with a GitHub or GitLab repository in both directions: edits in the GitBook editor land in the repo as commits, and commits pushed to the repo show up in GitBook. Sync is available on every plan including the free one, though only admins and creators can configure it. In specgit there is no second home. You open a file that already exists in your repository, edit it, and the save writes to that file as a commit under your own GitHub identity. specgit never keeps a copy of your documents or comments, and GitHub remains the source of truth. Git Sync does leave real Markdown in your repo, which answers most of the lock-in worry. What remains is a difference of direction. In GitBook the docs are made in the platform and the repo is a mirror you opted into; with specgit the repo is the only place they have ever been. That matters when the file is a spec engineers and AI coding agents read next to the code. ## How a change gets reviewed GitBook has its own review flow. You open a change request, teammates comment and approve inside GitBook, and when the space is synced you can also control who may push live by setting merge permissions on the Git side. Review happens where the writing happens, which suits a docs team that owns its publishing. specgit puts review in the pull request, and that inheritance is the strongest thing on this page. Highlighting a paragraph and commenting starts a real PR review thread an engineer can answer from GitHub without opening specgit. Publishing is a merge, so whatever your repo enforces is what happens: if a ruleset requires two approvals, specgit shows one of two and blocks the publish until the second lands. Authors request reviewers from the publish menu, reviewers approve or request changes under their own GitHub identity, and Publish when approved merges the moment the last approval arrives. Commits carry their author's name, the history stays complete, and the pull request CI your repo already runs, including link checkers, linters, and site builds, checks the doc change too. Every one of those controls already exists in an engineering org, already has an owner, and is already trusted. Choosing a platform's built-in review means configuring a second permissions and approval system and asking it to model the one you run for code. specgit uses the real one and puts a visual editor in front of it, so PMs, designers, and support teammates take part without a GitHub tab open. Teams whose reviewers are all writers, with no engineering review culture to inherit, will find GitBook's change requests more comfortable. ## Editing for people who do not write code GitBook's editor is block based and pleasant to use, with custom blocks and structured page hierarchies. A support lead or a PM can be productive in it on day one without seeing Markdown. specgit's editor points at a file in your repo. Nobody types Markdown, but what gets written is Markdown, and the flavor is broad: wiki links and embeds, callouts with custom titles and fold markers, highlights, footnotes, KaTeX math, YAML frontmatter, task lists, and inline Mermaid diagrams. Syntax specgit does not recognize survives byte for byte on save, so an editing pass does not quietly rewrite someone else's file. The rest follows from these being repo files: live co-editing, a redline View changes diff against main with selective undo, conflict resolution in the editor, and importing Word, PowerPoint, Excel, or PDF files by converting them to Markdown. [That migration path is covered here](https://specgit.com/google-docs-alternative-product-specs). ## Publishing and hosted docs sites GitBook renders and hosts the site. You get a documentation website with navigation, search, and a custom domain without running a build or picking a theme, and for a public manual that bundle is hard to argue with. specgit is not the renderer, though it does trigger the publish. Publishing merges to the base branch, which in a docs-as-code repo is the event that ships the site: a build wired to GitHub Pages, Docusaurus, MkDocs, Vercel, or Netlify fires on that merge exactly as it fires on an engineer's. What specgit leaves to the pipeline is the reader-facing layer, meaning themes, a custom domain, and site search. With no pipeline today and no appetite for setting one up, GitBook gets you a live site faster because the hosting comes bundled. With a pipeline already running, or a willingness to add a standard one, specgit is the editing and review layer in front of it: one copy of the content, no per-site platform cost, and the site updating on every merge. ## AI features GitBook bundles AI into its plans rather than selling it separately, including an assistant and an agent reachable from tools like Slack, Linear, and GitHub. It is aimed largely at readers of your published docs and at authoring inside the platform. specgit AI has three modes inside the editor, plus voice. Agent chat co-edits with you, Review posts inline comment threads on the draft like a human reviewer would, and Triage works through the open comments. Two rules apply throughout: AI runs only when a person invokes it, and every proposed change needs human approval before it is applied or posted. Routine usage records hold metadata rather than content, and AI requests run under xAI Zero Data Retention for API inputs and outputs and never train models. The Free plan includes one AI Review and one AI Triage run a month, which is enough to judge the output. Paid plans meter usage in dollars at published rates, with on-demand usage off by default until an admin enables it with a limit. ## How the pricing is shaped The two products bill on different axes, which matters more than any single number. GitBook charges per published site plus a per-user fee, so cost tracks how many sites you run and how many people are in the workspace, and its free plan is scoped to a single user. Current figures are on [GitBook's pricing page](https://www.gitbook.com/pricing). specgit charges per editing seat, and only editors count, so a reviewer who never types is never a seat. The Free plan covers unlimited collaborators on one repository with five publishes a month. Paid plans lift the repo and publish limits and add the AI co-editor; the breakdown is on [pricing](https://specgit.com/pricing). A rough rule: several distinct doc sites for a handful of people favors GitBook's shape, and a lot of people touching internal docs in one repository favors specgit's. ## Privacy and who holds a copy GitBook is a hosted platform, so your content is resident there whether or not you sync it to a repo. For a public documentation site that is exactly the arrangement you want, and Enterprise plans add controls like IP allowlisting for Git Sync. specgit is built the other way round. Zero Content Retention means specgit never keeps a copy of your documents or comments. The only things that touch specgit servers are temporary: live collaboration state while people edit together, AI you explicitly invoke, and a transcript if you choose to share one as feedback. Product analytics are content free and never receive documents, comments, prompts, repo names, or paths. Mechanics are on [security](https://specgit.com/security), architecture on [how it works](https://specgit.com/how-it-works). If your specs describe unannounced products, this is usually the criterion that decides it. ## The comparison at a glance The table runs both tools through the same criteria in the same columns. *GitBook and specgit on identical criteria.* | Criterion | GitBook | specgit | | --- | --- | --- | | Primary job | Publishing a hosted documentation site | Editing and reviewing docs that save into a GitHub repo | | Where the canonical copy sits | A GitBook space, optionally mirrored to a repo with Git Sync | The GitHub repo itself; specgit keeps no copy | | Review model | Change requests inside GitBook, plus Git merge permissions when synced | Real GitHub pull requests: required approvals, branch protection, rulesets, and repo CI all apply | | Editing for non-developers | Block-based visual editor | Visual editor on the repo file, no Markdown typed | | Public docs website | Yes, rendered and hosted by GitBook | Not rendered or hosted by specgit; publish merges to the base branch and your existing pipeline ships the site | | Markdown handling | GitBook's block model, synced to Markdown in the repo | Obsidian-flavored Markdown, unrecognized syntax preserved byte for byte | | AI | Assistant and agent bundled with plans | Agent, Review, and Triage in the editor, invoked by a person, every change approved by a human | | Pricing shape | Per site, plus a per-user fee | Per editing seat; viewing and commenting are free | | Free tier | Scoped to a single user | Whole team on one repository, five publishes a month | ## Pick GitBook if GitBook is the right answer more often than a page on our own site might suggest. - You want a public docs site with search and a custom domain, and you would rather buy the hosting than run a build pipeline for it. - A docs team owns the content and reviews its own changes rather than handing them to engineers. - You publish for customers, and the reading experience is part of the product. - You want AI aimed at readers of the published docs as well as authors. - Your content is not sensitive enough that a platform holding a copy is a problem. ## Pick specgit if specgit is narrow on purpose. It is the editor and the review layer over files you already own, and it hands rendering to whatever your repo already uses. - The docs are internal specs, decision records, or engineering documentation that belongs next to the code. - The files should stay plain Markdown in a repository you control, with no platform holding a copy. - Doc changes deserve the review apparatus your org already trusts: required approvals, branch protection and rulesets, reviewer assignment, per-line threads, attributed history, and the CI the repo runs. - Your repo already builds a docs site on merge, and you want the writing and the review to sit in front of that pipeline rather than inside a platform that keeps a second copy. - PMs, designers, and support teammates need to edit without learning Git or Markdown. [The full workflow is here](https://specgit.com/docs-as-code-with-non-technical-contributors). - Your docs folder uses Obsidian-flavored Markdown and wiki links, callouts, and embeds must survive an edit. [More on that setup](https://specgit.com/obsidian-github-collaboration). - AI coding agents in your repo should be reading the current spec, since they only see what is in the repository. ## Frequently asked questions ### Can specgit publish a public documentation website? It ships the site whenever your repo already builds one. Publishing from specgit merges to the base branch, and in a docs-as-code repo that merge is what triggers the deploy, whether the pipeline is GitHub Pages, Docusaurus, MkDocs, Vercel, or Netlify. So a publish by a PM in specgit puts the page live the same way an engineer's merge does. The limit is that specgit is not the host or the renderer: themes, a custom domain, and reader-facing search come from that pipeline. With no pipeline and no wish to build one, keep GitBook or a static site host on the rendering job and use specgit for the writing and the review. ### Does GitBook put my docs in my own repo? With Git Sync turned on, yes. GitBook mirrors the space to a GitHub or GitLab repository both ways, so edits in the editor arrive as commits and commits arrive back in GitBook. With specgit there is nothing to mirror, because the repo file is the only copy. ### Can we use both? Yes, and the split is a reasonable one. Keep the public site in GitBook and use specgit for internal specs and engineering docs elsewhere in the organization, since it works on Markdown and HTML files in GitHub. Where another tool also writes a file, specgit preserves syntax it does not recognize byte for byte. ### Does specgit work with branch protection and required reviews? Yes. Repos protected by branch protection or rulesets work end to end: specgit shows what is blocking a publish, authors request reviewers from the publish menu, reviewers approve under their own GitHub identity, and Publish when approved auto-merges when the last required approval lands. ### Do reviewers need a paid specgit seat? No. Seats count editors only, so viewing and commenting are always free. An engineer who reviews a spec and never types in it costs nothing, and can answer comment threads from GitHub instead. See [pricing](https://specgit.com/pricing). ### What Markdown does specgit support? Regular Markdown plus Obsidian-flavored Markdown: wiki links and embeds, callouts with custom titles and fold markers, highlights, footnotes, KaTeX math, YAML frontmatter, task lists, and inline Mermaid diagrams. Documents convert between the two flavors from the toolbar. ### Can I see the editor before installing anything? Yes. Open a Markdown file from any public GitHub repository at [/try](https://specgit.com/try) with no account and nothing installed. For your own repo, sign-in is through the specgit GitHub App: fine-grained repo-by-repo permissions with short-lived tokens rather than a broad OAuth grant. [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/docs-as-code-with-non-technical-contributors # Docs as code with non-technical contributors *Published 2026-08-02 · Updated 2026-08-16* Non-technical people contribute to docs as code by editing the repo file through a visual layer instead of a Git client. In [specgit](https://specgit.com/), a PM opens a document in a visual editor — from a template, an upload, or a file already in the repository — and the save becomes a commit on a branch under their own GitHub identity. Publishing opens a pull request. An engineer reviews it inline in GitHub, the same way they review code, and merging is what makes the change live. Nobody clones, branches, rebases, or types Markdown, and nothing about your existing docs-as-code setup has to change to allow it. ## The gap this fixes Docs as code works. Docs live in the repo, changes go through review, CI catches broken links and style violations, and the site rebuilds on merge. The problem is who can participate. The workflow assumes a person who is comfortable with a terminal, and most of the people with the information are not that person. So you get workarounds. The PM writes the update in a doc app and pastes it into Slack for someone to transcribe. Support files a ticket describing a wrong sentence and waits a week. A designer marks up a screenshot. Each one puts a human relay between the person who knows the answer and the file that needs to say it, and the update usually dies at one of those handoffs. The GitHub web editor is the usual half-fix, and it is genuinely better than nothing. But it hands a non-developer raw Markdown, a commit message field, and a branch dropdown, which is roughly the same ask with a nicer background color. The contribution rate does not move. ## What the workflow looks like Say support notices the docs describe a setting that moved two releases ago. The support lead opens the page in specgit from the repo file list, fixes the two sentences in a visual editor, and keeps writing. Saving happens automatically, and each save is a commit on a working branch, attributed to them, with history they can undo back through. When they are done they hit publish, which opens a pull request against your default branch. A writer or engineer reviews it. Comments left on a highlighted paragraph in specgit are real pull request review threads, so the reviewer can answer from GitHub without opening specgit at all. If your repo requires two approvals before anything lands, that rule holds: specgit shows the author what is blocking the publish, they request reviewers from the publish menu, and Publish when approved merges the moment the last approval arrives. Merging is the publish. Your CI runs, your site rebuilds, and the change is in the file's history like any other commit. *Every action in the editor maps to a GitHub primitive.* | What the contributor does | What happens in GitHub | | --- | --- | | Opens a doc from the repo | Reads the file at the current branch, no clone | | Types an edit | Nothing yet; the draft is a working branch | | Saves (automatic) | A commit on that branch, attributed to their GitHub account | | Highlights text and comments | A pull request review thread engineers can answer in GitHub | | Clicks publish | A pull request against the default branch | | Waits for sign-off | Branch protection and required approvals apply unchanged | | Change goes live | The pull request is merged; CI and your site build as usual | | Renames a file | A true git rename, so history follows the file | ## What the Git-fluent half of the team keeps This is the part that decides whether a docs owner will allow it at all. specgit adds an editing surface on top of what you run today, without adding a second system to maintain. Your writers keep their editors, their local previews, and their branches. Your generator keeps building from the same files. Your CI keeps running Vale, markdownlint, link checks, and anything else you have wired to pull requests, because a specgit publish is an ordinary pull request and gets checked like one. Branch protection and rulesets keep applying, since specgit merges through GitHub rather than around it. Review still happens in the pull request, so the review history stays in one place instead of splitting across two tools. There is no import step, no sync job, and no second copy of the content to keep aligned. specgit never keeps a copy of your documents or comments; GitHub remains the source of truth, and the temporary exceptions (live collaboration state while people edit together, AI you explicitly invoke, feedback you choose to share) are spelled out on [security](https://specgit.com/security). If you want the plumbing, [how it works](https://specgit.com/how-it-works) maps each editor action to its GitHub primitive. ## What the non-Git contributor never sees The list of things a new contributor does not have to learn before their first useful edit: - Cloning a repository, or installing anything at all. specgit runs in the browser. - Branches as a concept they manage. A draft is a branch, but it is presented as a draft. - Rebasing, force pushing, or resolving a conflict at a command line. When a conflict does happen, it is resolved in the editor. - Markdown syntax. They write in a visual editor and the file on disk stays Markdown, including Obsidian-flavored syntax like wiki links, callouts, footnotes, KaTeX math, frontmatter, and Mermaid diagrams, which render inline rather than showing up as code. - Commit messages, pull request titles, and the GitHub review UI, unless they want them. ## Getting people started without a migration You do not have to move a docs set to test this. Send someone [/try](https://specgit.com/try), where they can open a Markdown file from any public GitHub repository and edit it with no account and nothing installed. It is the real editor, so what they see is what they would get. For your own repo, everyone signs in through the specgit GitHub App: fine-grained, repo-by-repo permissions with short-lived tokens, no separate password and no broad OAuth grant. An individual can install it on their own account; an organization installs once through an admin, and members can request that install in one click. Then pick one page rather than a section. A page somebody has complained about twice is ideal, because you find out quickly whether the person who complained will fix it themselves. The Free plan covers unlimited collaborators on one repository with five publishes a month, which is enough to answer that question before anyone is asked to pay. Details on [pricing](https://specgit.com/pricing). ## Where this does not fit The honest limits, because finding them after a migration is worse than reading them now. - Markdown and HTML only. If your docs are authored in .mdx with React components, or in .rst for Sphinx, specgit cannot edit them today. Most repos never hit this: GitHub code search in July 2026 indexed roughly 24.6M .md files against roughly 0.32M .mdx, about 77 times more plain Markdown, which puts MDX near 1.3% of that pile. Where it does bite, it bites hard, because MDX concentrates in JavaScript and React documentation stacks like Docusaurus, Nextra, and Mintlify, so a dev-tool docs site whose pages carry embedded components is blocked today. Python documentation on Sphinx and .rst is out for the same reason. - GitHub only. The whole product is built on GitHub primitives, so a repo on GitLab or Bitbucket is not something specgit can open. - Repos where the docs are mostly binaries. A folder of PDFs, design files, or generated assets is not the target. specgit edits text files; existing Word, PowerPoint, Excel, and PDF files can be imported by converting them to Markdown, but that is a one-way conversion into the repo, not ongoing editing of the original format. - Publishing a site. specgit does not host or render a documentation website. Whatever generator or platform you use for that keeps doing it, and [the GitBook comparison](https://specgit.com/specgit-vs-gitbook) covers where that line falls. ## Why this is worth the setup The payoff is that the update happens at all, and that it happens where the change pressure is. A doc that lives in the repo sits in the path of the pull request that changed the behavior, so fixing it can be part of the same review instead of a task someone remembers on Friday. [The mechanism behind doc drift](https://specgit.com/blog/why-product-specs-go-stale) is mostly location, not discipline. The second reason is AI coding agents. They work from the repository, so a spec in a doc app is not context for them and a Markdown file two directories from the code is. Whatever a support lead corrects in the docs today is what an agent reads next week. If the people you are trying to enable are product managers specifically, [this guide covers the same ground from their side](https://specgit.com/docs-as-code-for-product-managers). If they are coming from a doc app, [Google Docs](https://specgit.com/google-docs-alternative-product-specs) and [Notion](https://specgit.com/notion-alternatives) both have their own comparisons, and there is a longer argument about [where specs should live](https://specgit.com/blog/notion-vs-github-for-product-specs). ## Frequently asked questions ### Can PMs edit docs in GitHub without learning Git? Yes. In specgit a PM opens the file, edits it in a visual editor, and the saves become commits on a branch under their own GitHub account. Publishing opens a pull request and merging makes it live. They never see a clone, a branch command, a rebase, or Markdown syntax, but the output is an ordinary commit history that engineers can read. ### Does this break our docs-as-code CI? No. A specgit publish is a normal pull request against your default branch, so every check you already run on pull requests runs on it: Vale, markdownlint, link checkers, build tests, previews. Branch protection and rulesets apply too, including required approvals and required status checks. ### What file formats work? Markdown and HTML files stored in a GitHub repository. Obsidian-flavored Markdown is supported, including wiki links and embeds, callouts, highlights, footnotes, KaTeX math, YAML frontmatter, task lists, and inline Mermaid diagrams, and syntax specgit does not recognize is preserved byte for byte on save. .mdx and .rst are not supported today. ### Do our writers have to change how they work? No. They keep their local editor, their branches, their preview server, and their generator. specgit is an additional way into the same files, not a replacement for the toolchain, and it does not require an import or a sync job because it reads and writes the repo directly. ### How do engineers review a change from someone who does not use Git? In the pull request, like any other change. Comments left on highlighted text in specgit are real pull request review threads, so an engineer can reply, request changes, or approve from GitHub without opening specgit. Reviewers who prefer to work inside specgit can approve there under their own GitHub identity. ### What does it cost to add a few non-technical contributors? Seats count editors only, so viewing and commenting are always free and a reviewer never consumes a seat. The Free plan covers unlimited collaborators on one repository with five publishes a month. See [pricing](https://specgit.com/pricing) for the paid tiers and how seats are measured. ### Can someone try it before we install anything? Yes. [/try](https://specgit.com/try) opens a Markdown doc from any public GitHub repo in the real editor with no account and nothing installed, which is a reasonable way to check whether the person you have in mind finds it usable before you ask an admin to approve the GitHub App. [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/blog/specgit-available-on-microsoft-marketplace # specgit is now available on Microsoft Marketplace *August 17, 2026 — the specgit blog* ![Microsoft Marketplace compare of specgit, Notion, and Confluence Cloud with Key Strengths and Best for Product Teams rows expanded.](https://specgit.com/blog/specgit-marketplace-compare-key-strengths.png) *specgit on Microsoft Marketplace, compared side by side with Ask Marketplace.* August 17, 2026 — Fn First Holdings today announced that specgit is available on [Microsoft Marketplace](https://marketplace.microsoft.com/en-us/product/saas/fnfirst-marketplace.specgit). Organizations can now purchase specgit through their existing Microsoft agreement and receive it on their Microsoft invoice. specgit is a browser-based document editor that saves to GitHub. Product managers and other non-engineers write and format the way they would in any modern editor; specgit performs the Git operations underneath. Saves become commits, comments become pull request review threads, and publishing merges the pull request. Engineers review documents in the same queue as code, and GitHub remains the source of truth. The offer is listed in Marketplace's AI Apps and Agents catalog. specgit's AI can co-edit a draft, review it with inline comments, and work through open comments — it runs only when a user invokes it, and every proposed change requires human approval. specgit retains no copy of customer documents or comments. ## Availability and pricing specgit Pro is $8 per user per month with a 14-day free trial. specgit Pro Plus is $16 per user per month and includes $10 of AI usage per seat each month. Annual billing reduces both by 20%. A seat covers an editor; viewing and commenting are free for unlimited people. Private offers are available for organizations that need custom terms. The listing supports Microsoft's Ask Marketplace, which builds side-by-side comparisons with similar products on request — [see specgit compared](https://marketplace.microsoft.com/en-us/compare?page=1&search=specgit&comparedProducts[]=fnfirst-marketplace.specgit&comparedProducts[]=aad.notion&comparedProducts[]=WA200003113). specgit is also sold directly at [specgit.com/pricing](https://specgit.com/pricing), and the editor can be tried without an account at [specgit.com/try](https://specgit.com/try). [All posts](https://specgit.com/blog) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/blog/organic-by-force # User insights belong in the repo *August 1, 2026 — the specgit blog* ![Two panel comic. In the first panel the boss says he trusts discovery and wants AI shipped only where customers choose it. In the second he orders the feature default-on with the off switch removed and calls it organic adoption for the QBR, while Alex mutters behind him.](https://specgit.com/blog/comics/organic-by-force.png) *This week's comic. The adoption target was the only finding anyone could still find.* ## It's a Product repo, not a Code repo As a recovering product manager, I spent countless hours making PowerPoints and documents that lived in shared drives or a company-wide permissioned document share — never even thinking about how engineers stored and managed their code. We'd collaborate in document editors and deal with the almost weekly 'save conflict' or 'version conflict' issues that even the best office suites experience. Maybe if I just rename the file `xxxx-final.docx` people will realize it really is the final version! Expand outward from PMs to designers and UX researchers, and they had their own assets in their own systems or document shares. What a mess. All the while our engineering friends have an amazing system in place that ensures one true source of truth, allows for divergent edits, and orderly merges into that source of truth. They've been doing it for years! AI-enabled coding turned me into a builder PM, and I've fallen in love with Git and pull requests. It's actually magic, and I'm baffled that the other product roles haven't caught on sooner and still seem trapped in their old ways of working. ## All product context belongs in the repo If this is not how your team works yet, it is usually because the spec and the research still live in a different tool from the code. When engineers build a feature, they pull up a spec, break it into tasks in a work item tracker (which likely also lives away from the code), and then hunt those external resources while writing code. That is a missed opportunity. No one would intentionally put silos between the implementation and the requirements for it — we just ended up here because the world we came from was siloed. But that world is dead. If you were designing a process from the ground up, you'd want every "context contributor" (product, UXR, design, support, data science, and so on) to contribute to engineering at the highest fidelity, and vice versa. A solution could be built for that — but what if one already exists and we just aren't using it? That's the repo! You might lack access or experience with it today, which is the first hurdle. The second is what specgit was made for — Git hosts like GitHub are underwhelming for context contributors. ## Put the research where the code already is 1. Sign in with a GitHub account and pick the repo. Empty is fine. You need write access to save; reading and commenting do not consume a seat. 2. Install the specgit GitHub App on that repo. Open a file that is already there, start from a template, or import Word or PDF. Put research notes, decision logs, and specs in a docs folder a human can actually find. 3. Point coding agents at that folder. In `AGENTS.md`, say where the docs live and that they are the source of truth for product intent, so an agent building the feature has the condition in context instead of only the ticket. 4. Collaborate in the repo the same way engineering does, but without worrying about the mechanics thanks to specgit. The editor at [/try](https://specgit.com/try) runs without an account. Connect a repo — empty is fine — and the free tier is one repository and five publishes a month, unlimited collaborators, no card. Seats count editors only; reading and commenting never consume a seat. [Pricing](https://specgit.com/pricing) has the rest. specgit never keeps a copy of your documents or comments. AI requests run under xAI Zero Data Retention for API inputs and outputs and never train models. The exceptions are narrow and written out on [privacy](https://specgit.com/privacy) and [security](https://specgit.com/security). [All posts](https://specgit.com/blog) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/blog/why-product-specs-go-stale # Why product specs go stale (and what keeps them current) *July 16, 2026 — the specgit blog* ![Four-panel comic: a product spec matches on kickoff day, drifts as decisions happen in tickets and PRs, then stays current when the team writes and publishes the spec in GitHub with specgit.](https://specgit.com/blog/why-product-specs-go-stale-comic.jpg) *Kickoff day vs six months later — the location problem in four panels.* Product specs go stale because the spec lives somewhere the product does not. The work happens in a GitHub repository. Code changes, a reviewer pushes back, the change merges. A page sitting in a separate documentation app has no connection to that and no way to hear it happen. For the page to catch up, somebody has to notice the drift, leave the tool they were working in, open another app, find the right document, and rewrite it, with nobody checking whether the rewrite was correct. Most weeks that somebody does not appear. So the spec keeps describing what the team meant to build in March, and the product does something else. Runbooks rot on the same mechanism. So do API guides and onboarding pages. Specs are the version people notice first, usually during a handoff or a customer question that the doc answers wrongly. ## The spec lives where the product does not Every decision that matters ends up in the repo. A pull request opens, someone argues with it, it merges. That sequence is the product changing shape. Anything outside the repo finds out later, if at all. Look at what has to happen for the doc to keep up. A person interrupts the work they are doing. They switch applications. They find the right page among however many exist, remember what the old wording claimed, and write a correction that no reviewer will read. Every one of those steps is somewhere the task can get dropped, and under a deadline it gets dropped at the first one. Teams tend to explain stale docs as a discipline failure. The same team keeps the code correct all day, because correcting the code is the work and because a reviewer catches them when they get it wrong. Neither of those forces reaches a page in another app. ## Signals a doc has already drifted Nothing announces the moment a document stops being true. It slides, and the first person to find out is usually the one who trusted it. A handful of checks surface the drift earlier than a confused new hire will: - Compare the last-modified date against how often that area of the product ships. If the surface has shipped several times since anyone touched the doc, the doc describes an older product. - Read the page with the shipped product open beside it. Field names, defaults, screenshots, and button copy go wrong before the concepts do. - Check who owns it. When the named owner left the company or moved to another team, corrections stopped arriving a while ago. - Watch chat. Engineers asking a question the doc already answers have either stopped trusting it or never found it, and both mean the doc is doing no work. - Listen for settled trade-offs coming back up. The reasoning that would end the argument is usually sitting in a resolved review comment nobody can locate. ## What a wrong spec costs A new engineer reads the spec and builds a mental model of the system out of it. If that spec describes a design abandoned during review, the model is wrong in ways the person has no way to detect, and it goes straight into their first few changes. Support and sales read the same page and end up describing the product as it was designed rather than as it shipped. Customers find that gap fast, usually in the worst context available. Then the re-litigation. A trade-off the team already settled gets argued again from scratch, because the argument that resolved it lives in a comment thread on a merged pull request and nobody remembers which one. ## Coding agents make a wrong sentence more expensive Agents raise how much code a team ships, so the surface any given spec describes moves faster than it used to. The doc expires quicker for exactly the same amount of neglect. There is a second problem. An agent that reads a stale sentence takes it at face value and builds against it. A human engineer would sense something was off and go ask in chat. The same property pays off once the spec is in the repo, because agents read the repository as context. A spec sitting next to the code steers the code, and nobody has to paste it into a prompt for that to happen. A spec in a separate app is invisible to the agent entirely. specgit's AI runs inside that same loop. Review posts inline comment threads on a draft, and Triage works through the comments that are open on it. Both run when a person invokes them, and every proposal waits for a human to approve it. ## Move the doc to where the change happens When the spec is a file in the repository that holds the code, the pull request changing the behavior can change the wording in the same commit. One reviewer sees both, and the review that already guards the code now guards the sentence describing it. Engineering teams have done this for years and call it docs-as-code. It shut out the people who write most specs, since it asked a product manager to learn Git and Markdown before they could fix a sentence. specgit removes that requirement with a visual editor over the repo, which is the whole argument in [docs-as-code for product managers](https://specgit.com/docs-as-code-for-product-managers) and [docs-as-code with non-technical contributors](https://specgit.com/docs-as-code-with-non-technical-contributors). ## Set up the review gate correctly Getting the doc into the repo does most of the work. Three settings make the difference between a folder people ignore and a folder that stays current: - Path-scoped reviewers come from **CODEOWNERS**, which maps `docs/` to the people who should see changes there. Branch protection is set per branch and cannot target a folder by itself, so the two work together: CODEOWNERS assigns the reviewer, branch protection makes the approval required before a merge. - Name an owner on the document rather than on the directory. Folder ownership diffuses until it means nobody, and a document with a named owner gets corrected when that person sees a change go by. - Freshness is already on screen. The last commit date says when the page changed and blame says who wrote which line, so nobody has to maintain a review banner at the top of the file for the team to know how old a claim is. ## What editing in the repo feels like In specgit a save is a commit under your GitHub identity. An inline comment is a pull request review thread, so an engineer answering it from GitHub and a PM answering it from the editor are in the same conversation. Publishing is a merge. If the repo builds a documentation site, that merge ships the site, though specgit is not the thing rendering or hosting it. [How it works](https://specgit.com/how-it-works) walks through the mapping. The tooling comparison is covered in [Notion vs GitHub for product specs](https://specgit.com/blog/notion-vs-github-for-product-specs). The short version for staleness: a page in a general workspace can be beautifully organized and still describe a product that stopped existing in April, because nothing in the workspace has any relationship to the merge that changed it. ## Start with one document Migrating a wiki wholesale is a project nobody has time for, and most of what would move is already dead. Pick one spec for something still in development, since that is the document people read while it changes. Export the Google Doc as Word and upload it. specgit converts it to Markdown in the repo through Microsoft MarkItDown, and from there the file behaves like every other file in the repository. Give it an owner, add the path to CODEOWNERS, and see whether the next change to that feature updates the wording in the same pull request. The free plan covers one repository and five publishes a month, with unlimited collaborators and no card. [Try it on a sample doc](https://specgit.com/try), or read the [pricing](https://specgit.com/pricing) if you want to know what happens after the first doc works. [All posts](https://specgit.com/blog) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/blog/notion-vs-github-for-product-specs # Notion vs GitHub for product specs *July 16, 2026 — the specgit blog* If your team uses GitHub, put the documents there. Not just the product spec: the handbook, meeting notes, runbooks, onboarding. The product changes through the repo, every edit keeps attributed history, and a merge can publish the page wherever it is meant to appear. A spec that lives in the repo can be edited in the same pull request as the code it describes, reviewed by the same people, and gated by the same required approvals. It is also context that AI coding agents read on their own. The catch used to be that touching repo files meant learning Git and Markdown. specgit removes that catch by putting a visual editor on the same files. Notion still wins at interactive databases: filtered views, rollups, relations, and a board you drag cards across. That is a different job from writing team documents. What follows is the honest version of that call. Updated July 17, 2026: specgit adopted content-free product analytics. This article's privacy comparison now reflects the current policy; see [Privacy](https://specgit.com/privacy) for the complete disclosure. ## When is Notion the better choice? Notion is genuinely good at what it was built for. Writing is fast, and databases and relations make roadmaps and trackers easy to keep. Sharing is flexible, and a non-technical teammate never feels like a guest in someone else's tool. Pick Notion when the artifact is really a database with a page attached, like a launch tracker or an interview log with filtered views. Pick it when the team has no GitHub account. Do not pick it for the handbook or meeting notes if the team already lives in GitHub: those belong in the repo too, and a connected pipeline publishes them the same way a spec publishes. None of that is in dispute here. If you are unhappy with Notion for reasons that have nothing to do with specs, [the wider alternatives roundup](https://specgit.com/notion-alternatives) covers that field separately. ## When does GitHub win for a spec? GitHub is built for documents that have to be reviewed and have to stay true. Changes go through pull requests with named approvals and rules the repo enforces, and branch protection can require a second reviewer before anything lands. History is permanent and attributed, so every change has an author, a timestamp, and a diff. Repo permissions are the same system that already governs the code, run by the same admins. Then there is proximity. The code that defines what the product actually does is one directory away. Engineers work there all day. So do AI coding agents, which read files in the repo as context without anyone exporting or connecting anything first. ## How do engineers review specs in each? In Notion an engineer leaves a comment. The comment is useful and the thread resolves, but nothing gates the document on their sign-off, and the review happens in a tool they open only when a link sends them there. In GitHub a spec change is a pull request. Comments attach to specific lines, threads resolve, and required approvals hold the merge until the named people approve. That is the same muscle memory engineers use for code, in the same tab, in the same notification stream. In practice it means spec review happens instead of being scheduled. The PM side of that does not have to look like GitHub. In specgit you highlight a paragraph, leave a comment, and it becomes a pull request review thread the engineer answers from GitHub. [How it works](https://specgit.com/how-it-works) maps each action: saves are commits, comments are pull request threads, publish is a merge that honors whatever approvals your repo requires. ## Which one stays current longer? The repo copy, and the reason is mechanical rather than cultural. A spec describes the product, and the product changes through the repo. Every scope cut, edge case decision, and constraint forced by a vendor eventually lands there as code. A page in Notion has no way to receive any of it. Somebody has to leave the repo, open the workspace, find the page, and edit it, with no review attached and nothing enforcing the habit. A spec in the repo can change in the same pull request as the code, reviewed by the same people. This is why specs in workspace tools drift no matter how organized the team is. The full mechanism, and how to spot documents it has already caught, is in [why product specs go stale](https://specgit.com/blog/why-product-specs-go-stale). ## How do the two compare point by point? For specs specifically: - **Writing.** Notion's editor is more polished out of the box. specgit gives you a visual editor on repo files, so nobody writes raw Markdown either way. - **Review.** GitHub has pull requests with required approvals. Notion has comments, with no way to gate a change on sign-off. - **History.** Every save in the repo is a commit, kept for as long as the repo exists. Notion's page history retention varies by plan. - **Permissions.** Repo access is one system shared with the code. A Notion workspace is a second permission system to administer. - **AI agents.** Repo files are context automatically. Workspace content needs an integration before an agent can see it. - **Automation.** A doc change is a pull request, so the checks your repo already runs on one apply to it, and a merge triggers whatever build ships your docs site. Getting a Notion edit to do either takes an integration you build and maintain. - **Getting existing content in.** Both import. specgit converts Word, PowerPoint, Excel, and PDF files to Markdown in the repo. - **Measurement.** Notion offers page analytics tied to viewers and pages. Product analytics are content-free and processed by PostHog Cloud EU. Restricted or unknown regions send nothing before separate opt-in; elsewhere public events are cookieless and unidentified and signed-in events are pseudonymous with opt-out. No ad tech, sale, or retargeting. See Privacy for retention and rights. ## Who holds your docs? In Notion, your docs live in Notion's cloud, exportable but resident there. In the repo approach they are plain Markdown files in a repository you already control. With specgit, specgit never keeps a copy of your documents or comments — GitHub remains the source of truth. The details are on our [security page](https://specgit.com/security). For most teams this is a tiebreaker rather than the headline. It weighs more if your specs cover unannounced products or pricing changes, because then it matters that GitHub stays the source of truth and that product analytics never receive content. ## Can a PM work in GitHub without learning Git? Yes, and that is the whole reason [specgit](https://specgit.com/) exists. You open the doc, type, and save. The save is a commit with your name on it. You never write Markdown syntax, and you never see a branch name unless you go looking for one. When a repo requires approvals, the publish menu tells you what is blocking it, such as needing two approving reviews when one has landed, and you can request reviewers from the same menu. Choosing publish when approved merges the moment approval arrives. The rest of the team matters as much as the PM here. [What changes for non-technical contributors](https://specgit.com/docs-as-code-with-non-technical-contributors) covers designers, support, and anyone else who needs to leave a comment without sitting through a Git tutorial. If your engineers already use the phrase docs as code, [here is what it means for product managers](https://specgit.com/docs-as-code-for-product-managers). ## So which should your team pick? Split it by what the file actually is, and be honest about what each side is bad at. - **Notion is best for** interactive databases and relations: filtered views, rollups, and a board you drag cards across. Its limitation for team documents: a page there has no way to receive changes made in the repo, so it goes out of date unless a person maintains it by hand. - **GitHub with specgit is best for** the team's documents if the team uses GitHub: specs, handbooks, meeting notes, runbooks, onboarding. They sit next to the code, change through pull request review, keep permanent attributed history, and are read as context by the AI coding agents already working in that repo. Its limitation: a Markdown file is not a queryable database, so the filtering, sorting, rollups, relations, and drag-and-drop boards Notion gives you are not there. Tables, task lists, and linked pages are, and the tracking half is usually covered by GitHub Issues and Projects, which your engineers are already in. Putting a non-engineering team on any of this takes one setup conversation Notion does not need. ## What about the other tools in this decision? The same meeting usually raises a few neighbors. If you are comparing documentation platforms rather than workspaces, [specgit versus GitBook](https://specgit.com/specgit-vs-gitbook) is the closer match. If your writers keep an Obsidian vault, it is already a folder of Markdown, and [Obsidian plus GitHub](https://specgit.com/obsidian-github-collaboration) covers adding team review to it with wiki links and callouts preserved. Coming from Google Docs rather than Notion, [the same comparison holds](https://specgit.com/google-docs-alternative-product-specs). If the first drafts start in an AI PRD tool, the open question is [where that draft lives afterward](https://specgit.com/blog/prd-chatbot-vs-docs-in-the-repo). You can open the editor on a repo without signing up from the [try page](https://specgit.com/try). The free tier covers one repository and does not ask for a card, and [pricing](https://specgit.com/pricing) has the numbers for a team. [All posts](https://specgit.com/blog) | [Back to specgit](https://specgit.com/) --- ## Source: https://specgit.com/blog/prd-chatbot-vs-docs-in-the-repo # PRD chatbot vs docs in the repo *July 16, 2026 — the specgit blog* There's a fast-growing category of product tools: AI that writes your PRD. ChatPRD is the best-known example, and new ones keep arriving — describe the feature to a chat interface trained on PM frameworks, answer some questions, and get a structured document in minutes. These tools are genuinely useful, and this isn't a takedown. But they answer a different question than the one most teams are actually struggling with. Drafting a PRD was never the expensive part. The expensive part starts the moment the draft exists. Updated July 17, 2026: specgit adopted content-free product analytics. This article's privacy comparison now reflects the current policy; see [Privacy](https://specgit.com/privacy) for the complete disclosure. ## What AI PRD generators do well Credit where it's due. A good PRD chatbot kills the blank-page problem — you go from a vague idea to a structured document with goals, user stories, and success metrics in one sitting. The frameworks baked in act as a checklist, so you don't ship a spec that forgot edge cases or rollout. For newer PMs, the interviewing style is real coaching: the tool asks the questions a senior PM would ask. If your bottleneck is producing first drafts, these tools solve it. That's a real problem and a fair win. ## The question a PRD generator doesn't answer Here's the part the category leaves open: once the draft exists, where does it live? In practice you export it — to Notion, Google Docs, or a PDF in Slack — and from that moment it's a snapshot. The product keeps changing through the repository (scope cuts, edge-case decisions, design changes forced by constraints), and nothing carries those changes back into the document. This is the same drift mechanism that kills hand-written specs — [we wrote up exactly how it works](https://specgit.com/blog/why-product-specs-go-stale) — and generating the doc with AI doesn't change it at all. If anything, faster drafting means more documents drifting in more places. A PRD generator makes the snapshot cheaper to produce; it doesn't make it stay true. ## How engineers actually review specs The second open question is review. A PRD isn't done when it's written — it's done when engineering has pulled it apart and signed off. Engineers do that in pull requests: inline comments on specific lines, threads that resolve, required approvals that gate the merge. That's where their review muscle memory and their tooling already are. A spec that arrives as a pull request also picks up the rigor the repo already has, without anyone configuring it for docs: CODEOWNERS names the reviewer, branch protection holds the change until that person signs off, and the checks the repo runs on any pull request run on this one too. A doc in a chatbot's workspace or an exported page has none of that. You get general-purpose comments at best, no way to require sign-off before the spec is treated as agreed, and no record connecting the spec's evolution to the decisions that drove it. The review conversation ends up scattered across Slack and meetings instead. ## The comparison at a glance They're different jobs, so compare them honestly: - **First draft** — the PRD generator wins. Structured drafts in minutes, frameworks included. - **Source of truth** — docs in the repo win. The spec can change in the same pull request as the code it describes; an exported draft is a snapshot from day one. - **Engineering review** — docs in the repo win. Pull request threads, required approvals, and a permanent record versus general-purpose comments. - **Staying current** — docs in the repo win. Repo docs sit in the path of every product change; generated docs drift like any other doc. - **AI coding agents** — docs in the repo win. Files in the repository are context agents pick up automatically; a doc in another app is invisible to them. ## Isn't specgit AI just another PRD chatbot? Fair question, since [specgit](https://specgit.com/) has AI too. No — and the difference is the point. specgit's job is making the repo a place PMs can work: you write in a visual editor in the browser, saves are commits attributed to you, comments are real pull request threads engineers answer from GitHub, and publish is a merge honoring the approval rules your repo already enforces. specgit never keeps a copy of your documents or comments — GitHub remains the source of truth. Product analytics are content-free and processed by PostHog Cloud EU. Restricted or unknown regions send nothing before separate opt-in; elsewhere public events are cookieless and unidentified and signed-in events are pseudonymous with opt-out. No ad tech, sale, or retargeting. See Privacy for retention and rights. specgit AI is an optional co-editor on top of that — Agent chat edits the document with you, Review posts inline comment threads like a human reviewer, Triage works through open comments. It only runs when you invoke it, and every AI-proposed change waits for your approval before anything is applied. It's not a PRD generator with your docs held inside it; it's assistance on files that stay yours, with a human sign-off on every change. ## Use both — but put the truth in the repo There's no conflict here. If a PRD chatbot makes your first drafts faster, use one. The decision that actually determines whether your specs stay true is where the canonical version lives — and that should be the repository, next to the code, where changes are reviewed and drift is fixable in the same pull request. If your engineers call this docs as code, [here's what it means for product managers](https://specgit.com/docs-as-code-for-product-managers). We've written the same comparison for teams coming from [Notion](https://specgit.com/blog/notion-vs-github-for-product-specs) and [Google Docs](https://specgit.com/google-docs-alternative-product-specs) — the verdict rhymes. Plans start free; see [pricing](https://specgit.com/pricing), or [try it on a sample doc](https://specgit.com/try) first — the real editor, no account required. [All posts](https://specgit.com/blog) | [Back to specgit](https://specgit.com/)