Frequently asked questions
Answers to common SpecsGraph questions about the hosted service, agents, Git, the review flow, your data and the plans for SpecsGraph Cloud.
Product
Who is SpecsGraph for?
AI-native software teams: product managers, business analysts, developers and QA engineers who build software with AI agents and want one source of truth that people and agents both work from. A single developer can use it as well, accepting their own agent's staged changes. AI-native software development describes how the roles work together.
How is this different from a wiki?
A wiki stores pages of prose. SpecsGraph stores a typed spec: bounded contexts, aggregates, use cases, features with scenarios, glossary terms and roles, which tools can query and agents can stage changes to. Core concepts lists the building blocks.
Do I have to write every spec by hand?
No. Agents stage changes from your prompts and your codebase, and people accept, question or withdraw them. People edit directly in a workstream too. See How the spec workflow works, and Start from an existing codebase for software that already runs.
Agents
Which agents work with SpecsGraph?
Any agent that supports MCP over streamable HTTP. There are guides for Claude Code, Codex, Cursor and GitHub Copilot; other MCP clients connect the same way.
Can an agent change the spec without a person approving it?
Not by default. An agent only stages: what it writes waits in the workstream's proposal until a person accepts it, and agents cannot mark a task Ready or answer a question; they propose plans and ask. A project with Agent autonomy on lets agents with read and write access write the workstream and take those acts. Either way, nothing reaches Main until a person publishes a task. How the spec workflow works explains the rules.
Can an agent mark code as done?
No. An agent claims a work item and records its pull request; the merge of a pull request that names the item, or a person, marks it done. Recording a verify or uat result and marking existing code as implemented on the Build page are a person's acts too, even with Agent autonomy on. See Work items and delivery.
Do connected agents count as seats?
No. A seat is any person who can sign in, or an invitation that is still pending; agents act for a member and do not count. Cloud plans has the details.
How does an agent authenticate?
Most clients sign in with OAuth: they open SpecsGraph in your browser and you allow them on a consent page. Clients without sign-in use a personal access token that you create in SpecsGraph; tokens start with sgp_, so secret scanning can catch a leak. You can revoke either at any time, in Settings, then Access tokens. Either way the agent acts for you and never with more rights than you have; see Personal access tokens.
Delivery
How do I know which parts of the spec are built?
Open the Build page. Each artefact on Main shows a status derived from work items, merges and deployments: Not started, Planned, In dev, Merged, On an environment, Verified, Outdated when Main changed since it was built, or Rolled back. See Build status.
Does SpecsGraph replace Jira or our tracker?
No. Tasks, work items and milestones carry tracker keys that link to your tracker, and the optional Jira mirror reads the status of verify and uat items. SpecsGraph never writes to Jira and has no sprints, estimates or boards. See Work items and delivery and Roadmap.
Git and repositories
How does the spec stay in step with the code?
Each published task is a commit in your repository, usually through a pull request next to the code change, so the spec and the code share one history and one review. See Spec files in your repository.
What does SpecsGraph write to my repository?
Only the project's spec folder (default .specsgraph): one YAML file per artefact and a generated README.md. Changes arrive as a pull request from a branch spec/<project key>/t-<n>-<name> per task, or as direct commits; see Branches and pull requests.
Does SpecsGraph work with GitLab, Bitbucket or GitHub Enterprise Server?
GitHub (through the SpecsGraph GitHub App) and GitLab, including a self-managed GitLab (through an access token), are supported for publishing, and both can be sign-in providers. Bitbucket is not. For GitHub Enterprise Server, talk to us. See Connect GitHub or GitLab.
Can I undo a change to the spec?
Before it publishes, yes: discard an unrouted change, withdraw a staged revision, or abandon the task (its changes return to the workstream) or the workstream. After it lands, edit the artefacts back in a new workstream and publish that task; reverting a published task in one step is not available yet. Reverting the files in Git alone leaves Main out of step, and the next publish of those files is blocked until an Admin overwrites them. History and versions shows what changed and when.
Hosting
Who runs SpecsGraph?
We do. SpecsGraph is a hosted service: we run the servers, apply upgrades and security patches, keep the backups and operate the GitHub App that publishes your specs. Your team signs in and works; there is nothing to install.
Can I run SpecsGraph on my own servers?
No. SpecsGraph is offered only as a hosted service. If your organization has strict requirements, the Enterprise plan is planned to include dedicated single-tenant hosting in your region; talk to us about it.
Do I need to upgrade SpecsGraph?
No. SpecsGraph Cloud always runs the current release, so you never schedule an upgrade.
Pricing and support
When will plans be available?
Now. Solo is USD 20 per month for one person, and Team is USD 20 per seat per month, for 2 to 50 seats; both are plus tax where applicable. Subscribe from the pricing page, which shows every plan. Enterprise comes later; talk to us about it.
Can I get paid support?
Not as a separate plan. Every plan gets the same support: email and the community on Discord; see Get help. Enterprise contracts can add a named account lead.
What happens to my data if I stop using SpecsGraph?
Your published spec lives in your repository with your code. Everything else (workstreams, proposals, threads, tasks, members) can be exported as one archive from the organisation settings, then Export at any time. Security and your data lists what is stored.
Help
Where do I get help?
Troubleshooting covers common problems with sign-in, Git, publishing, reviews, agents and notifications, and lists where to ask: the community on Discord, or email us.
Next steps
- Quickstart: sign in and try the full workflow.
- Troubleshooting: fixes for common problems.
- Core concepts: the vocabulary behind these answers.
- Cloud plans: the plans, and how seats are counted.