CrystalSpec beginner's guide
A product spec is a shared plan for what your product should do. In five short stages, you will describe one user goal, turn it into a flow, check the draft, and publish it for your team.
New here? Start small. One role, one phase, one flow, and a few steps are enough for a useful first draft.
Choose how to begin
Already have notes? Let AI create a draft. Repeating a familiar project? Use a template. Learning with one small feature? Start blank. Every part remains editable.
Paste notes or add documents. CrystalSpec may ask up to five optional questions, then creates a draft for you to review.
Choose a ready-made spec or a template your team saved from an earlier published project. You can change it after creation.
Start with an empty spec and add only what you need. You can still ask AI for help later.
When the project opens, start with its Draft revision. With AI, generation may take a few minutes and continues if you leave the page.
Six words before you start
You do not need to memorize these. They are here so the next five stages read like instructions, not a secret handshake.
Set up the basics
Start with three basics: who needs help, what goes wrong today, and what should improve. Then create the names and groups you will reuse.
Dashboard → More actions → Edit Project Details; then Dashboard → Roles, Terminology, Phases, and Epics
“A buyer can resolve a failed payment without contacting support.”
This says who needs help and what success means. “Build a retry endpoint” only names one possible solution.
In Description, say who has the problem, what happens today, and what should be different. Leave technical solutions out unless they are required.
A role is a person or system that takes part, such as Buyer or Payment provider. Add a terminology entry for any word a new teammate might misunderstand.
A phase says when work is planned, such as First release. An epic is an optional group of related flows, such as Payment recovery.
Good enough for now
Create your first flow
A flow shows what happens from the moment a person or system starts something until it succeeds or fails. Begin with the expected path, then add important alternatives.
Sidebar → Flows → New Flow
Prefer “Recover a failed payment” over “Payment handler.”
The first name tells a reader what success looks like. The second names machinery and hides the buyer's journey.
Name it after the result, such as Recover a failed payment. Choose its required phase. Choose an epic only when it helps group related flows.
A trigger is the event that starts the journey. Choose User when a role starts it, or Time when it starts on a schedule.
Turn on editing and select Add new step. For each step, choose the responsible role and describe something a reader can observe.
Add decision steps for important choices and failures. Add test cases for the results that matter. Create a data model only when the flow reads or changes information that needs a shared definition.
Good enough for now
Check and improve
AI can find missing cases and draft changes, but you choose what enters the spec. Ask for one clear result, then inspect every suggestion.
Project-aware AI Agent → Start talking to the AI Agent
“Find any path in the failed-payment flow where the order could remain in an unclear state.”
It names the flow and the exact problem to look for. “Make this better” leaves too much open to interpretation.
Name the flow and the task: find a missing payment-recovery path, draft test cases, or explain a Spec health finding. Some replies are advice only, with no changes to review.
Open AI Proposed Changes and use Details to inspect each addition, edit, or deletion. Suggestions start as Approved, so change incorrect ones to Deny.
Select Submit after your review. Nothing changes before you submit. If another person owns the draft, CrystalSpec blocks the change until the edit lock is available.
Good enough for now
Preview and publish
You make changes in a draft revision. Publishing saves that work as a fixed revision your team can rely on. Read the whole draft before you publish.
Preview in the project header; Dashboard → Spec health; Tools → Analyzer; Draft revision
Coordinate before taking over another person's draft.
A project has one draft and one editor. An owner or admin can take over, but doing so discards the other person's unpublished work.
Read the spec as a new teammate would. Check that the project description, flows, steps, and data models agree.
Spec health finds missing structure. On a project that was already published, its Dashboard card checks the published revision, not your open draft. Analyzer is an optional AI review and uses AI credits.
Select Draft revision, expand What changed, and write a Revision Message that says what changed and why. Select Publish, or Send for approval when your workspace requires it.
Good enough for now
Keep it current
A spec stays useful only while it matches the product. Record decisions near the affected flow, update delivery status, and share a published revision.
Flow → Discussions; Tools → Tracker; More actions → Share
Update the spec when a product decision changes.
Small revisions are easier to review and leave a useful history. No quarterly archaeology expedition required.
Use a flow's Discussions tab for questions and decisions about that flow. Discussions remain available after you publish and do not take the edit lock.
In Tracker, update flows and steps as work moves forward. Tracker status is separate from the spec, so it can change without opening a draft.
Use Share for a read-only link to the current published revision. Drafts are never exposed. When agreed behavior changes, start a new draft, update it, and publish again.
Good enough for now
The final check
A useful spec is easy for a new teammate to follow and clear about what happens when things go wrong.
Ready to try it?
Bring the notes you already have or begin with a blank project. Your first spec does not need to cover the whole product. It only needs to make one useful result clear.