Sutra sits between your product decisions and your AI coding agents. Build implementation-complete specs — with acceptance criteria, edge cases, API contracts, and dependencies — then export them in formats agents can act on immediately.
"A computer can never be held accountable, therefore a computer must never make a management decision."
— IBM, 1979
Sutra exists because this is still true.
AI agents are powerful. They are also literal. They build exactly what you tell them — no more, no less. When the spec is vague, the agent guesses. When the agent guesses, nobody is accountable for the outcome.
The question is whether your decisions are precise enough to execute.
Sutra turns your intent into implementation-complete specs — with acceptance criteria, edge cases, API contracts, and test types — so the agent builds what you actually meant, not what it assumed you meant.
You define the intent. You set the scope. You own the edge cases. The agent executes.
Your name is on the spec. The agent's name is on the code. That's the right order.
Sutra is a story mapping tool built for teams using AI coding agents. Traditional Jira tickets are written for humans — thin, ambiguous, and leaving implementation decisions to the developer. AI agents need more: testable acceptance criteria, edge cases, API contracts, test type declarations, and dependency maps that tell the agent what it can call autonomously vs what needs a human in the loop.
Sutra gives you a structured canvas to build that context, sync it with Jira, and export it in agent-ready formats.
The mental model: Sutra is your spec authoring environment. Jira is your delivery tracking system. Sutra doesn't replace Jira — it completes it. Jira is the source of truth for status, sprint, and assignee. Sutra is the source of truth for specification.
Enter project name and Jira key. Blank canvas — add epics, flows, and stories manually. All fields are available from the start.
Enter project key, fetch epics, select which to import. Stories land with Jira keys pre-linked.
Import a previously exported Sutra JSON. Full fidelity — all flows, NFRs, API contracts, and spec fields preserved.
| Element | Interaction |
|---|---|
| Epic header | Double-click to rename inline · ✎ Edit Epic to open modal — title is editable at the top of the modal · Drag ⠿ to reorder · Right-click for context menu |
| Flow header | Click ✎ to edit name, description, API contracts · Drag ⠿ to reorder · Right-click for context menu |
| Story card | Click to select for push · ✎ to edit · ⧉ to duplicate · Right-click for context menu |
| Jira pill | Click MBA-12 pill on any story to open that ticket in Jira |
| Progress bar | Spec completeness per flow and map-wide. Hover topbar bar to see gaps. |
| Zoom | − % + controls in toolbar, or Ctrl+scroll on canvas |
| Quick-jump strip | Sticky bar at canvas bottom — click any epic pill to scroll it into view |
AC: ... per line. Supports markdown.| Field | What it does |
|---|---|
| Description | One-paragraph overview of the system and who it serves |
| Goals | Measurable business outcomes — the agent understands success criteria |
| Out of Scope | Explicitly excluded features — prevents the agent building things you don't want |
| Tech Stack | Drives test framework resolution — integration tests on frontend-only get Jest + MSW, not Supertest |
| Global NFRs | Cross-cutting constraints applied to every epic and story in the spec |
| Engineering Notes | Architecture decisions, coding conventions. Agent reads this before touching any file. |
| Releases | Milestones or phases. The exported Build Instructions targets the first release. |
Existing codebase? Click + Insert Template in Engineering Notes to add a structured block telling the agent what's already built and where — preventing rewrites of working code.
A major functional area or user journey. Contains flows. Maps to a Jira Epic. Has description, NFRs, and optional screen map.
A user journey step within an epic. Contains stories. Has description and structured API contracts. A Sutra concept — not a Jira issue type.
An atomic requirement. Maps to a Jira issue. Has AC, edge cases, test type, and dependencies. The unit the agent implements.
Start from scratch, import from Jira, or generate from a document using the AI template. Your map is the spec authoring surface.
Add acceptance criteria, edge cases, test types, dependencies. Add API contracts to flows. Set NFRs at epic or global level.
Push enriched stories — creates new tickets or updates existing ones. Push epics with full flow and API contract context.
Export as single markdown spec or Claude Code project structure. Drop into your repo and run your agent.
Sutra uses your existing browser session — no API key required. Open your Jira instance and log in before using Jira features.
Click ⚙ Settings in the sidebar. A blue dot appears on first install to signal unvisited settings. The Jira tab opens by default and shows a contextual tip explaining the setup.
Paste https://company.atlassian.net (no trailing slash). Works for Jira Cloud and self-hosted. The ⚠ badge on Settings disappears once set.
Click the project key pill in the topbar. Required before any push.
Jira is the source of truth for delivery. Sutra is the source of truth for specification. Use both — they serve different purposes.
| Scenario | What happens |
|---|---|
| Story with no Jira key | Creates a new issue. Stamps the key on the story card. |
| Story with Jira key | Updates the existing issue — title and description/AC only. Never touches status, assignee, or sprint. |
| Bulk push | Select stories by clicking cards (or Select All on epic header) → Push Stories in topbar. |
| Single story push | Right-click any story card → Push to Jira / Update in Jira. |
| Epic state | Button shown | What happens |
|---|---|---|
| Not linked to Jira | ⬆ Push to Jira | Creates a Jira Epic. Stamps key. Description populated with NFRs, screens, numbered flows, and API contracts. |
| Linked, has content in Sutra | ⬆ Update [key] | Overwrites the Jira epic description with current Sutra content. |
| Linked, empty in Sutra | ⬇ Sync from Jira | Pulls title and description from Jira into Sutra. |
Issue type validation: Sutra validates the issue type before linking. Entering a Story or Task key instead of an Epic shows an error and refuses to link.
Syncing an epic pulls title and description as plain text. Flows, NFRs, and API contracts do not reconstruct as structured Sutra fields — the content is in the description but not visualised as cards. Workaround: use Export JSON as your source of truth for round-trips. Import the JSON, not the Jira epic.
Stories created directly in Jira don't have test type, edge cases, or dependency maps. After importing, add these fields manually in the Spec and Dependencies tabs before exporting to an agent.
Clicking ⬆ Update [key] overwrites the entire Jira epic description. Manual edits made directly in Jira will be lost. Always edit epic context in Sutra, not in Jira.
Status, assignee, sprint, priority, labels — Sutra never reads or writes these. Fully managed in Jira. Sutra only pushes title and description/AC.
One markdown file — overview, tech stack, NFRs, every epic and story with full ACs, edge cases, API contracts. Paste into any AI assistant or share for review.
A zip ready to drop into your repo. Root CLAUDE.md, one folder per epic, full spec.md. Includes auto-generated Build Instructions. Run Claude Code immediately.
Full lossless map data. Share between machines, feed to AI, or back up. Import back via New Map → Import → From File.
The root CLAUDE.md includes a Build Instructions section auto-populated from your release plan, epic order, test framework mapping, and global NFRs. The agent reads this before writing a single line of code.
Sutra resolves the correct test framework from your declared tech stack. Never recommends Supertest for a frontend-only project.
| Test Type | Stack | Resolved Framework |
|---|---|---|
unit | Any | Jest unit test |
integration | Frontend only | Jest + MSW (mocked browser APIs) |
integration | Backend only | Supertest integration test |
integration | Full-stack | Supertest (API) or Jest + MSW (frontend) |
e2e | Web | Playwright E2E test |
e2e | Mobile only | Detox E2E test |
Set organisation-wide non-negotiable constraints once in ⛨ Org Guardrails in the sidebar. They're injected at the top of every spec export across all maps — every agent session starts with them, regardless of project.
First time you click ⛨ Org Guardrails, a brief explainer appears. The amber dot on the button disappears after your first visit.
Download from Settings → Utilities → Download AI Map Template. This JSON contains a master prompt and full schema. Give it to Claude with your PRD, BRD, or ICD — Claude generates a fully structured Sutra JSON you import directly.
Settings → Utilities → Download AI Map Template
Open claude.ai → upload template JSON + your document in the same message
Prompt: "Follow the instructions in _sutra to generate a story map from this document. Return only valid JSON."
Save JSON → Sutra → + New Map → Import → From File
For ICDs: Tell Claude "treat the entire document as one Epic." For PRDs covering multiple features, Claude decomposes into multiple epics automatically.
You have a requirements document and want a fully populated Sutra map without manual entry.
Settings → Utilities → Download AI Map Template. Contains master prompt and full schema.
Open claude.ai. Upload the template JSON and your PRD or ICD as attachments in the same message.
"Follow the instructions in the _sutra block to generate a Sutra story map from the attached document. Return only valid JSON with no markdown fences."
Save Claude's output as a .json file. In Sutra: + New Map → Import → From File.
Claude does a good first pass but won't get everything right. Review each story — fill in edge cases, add API contracts to flows, verify test types.
You want to catch spec gaps and get an implementation plan before handing the spec to an agent. A human-in-the-loop review pass before the build starts.
Export JSON from the topbar. Full structured spec — every field, every story.
Upload to claude.ai. Prompt: "Read this Sutra story map. Identify spec gaps, ambiguous AC, and missing edge cases. Produce an implementation plan — story sequencing, dependencies, open questions. Do not generate code. Return the updated JSON with planning notes in the relevant openQuestions fields."
Claude returns a plan and updated JSON. Resolve conflicts, answer open questions, adjust story scope.
+ New Map → Import → From File. Planning notes appear as open questions on stories. Resolve them, then export the final spec for building.
Importing Claude's JSON creates a new map — it does not overwrite your existing one. Review both before deciding which to keep.
Adding features to an existing product. You don't want the agent to rewrite working code.
Click + Insert Template in the green Existing Codebase card. A structured block is appended to your engineering notes.
Set the codebase root path. List what's already built per epic. Add key files the agent should read first.
Engineering notes land verbatim in root CLAUDE.md. The agent reads this before touching any file — extends existing code instead of rewriting it.
You built a map in Sutra and want to share it with a teammate or use it on another device.
Export as JSON from the topbar. Lossless — all epics, flows, stories, NFRs, API contracts preserved. Share the file or import on another device.
Create empty map → import epics from Jira → sync each epic. Stories import with Jira keys. Flows, NFRs, and API contracts won't reconstruct as structured fields — they'll be in the description as text.
Use for Jira-native epics only. For Sutra-originated content, always use JSON.
| Shortcut | Action |
|---|---|
| Ctrl + Scroll on canvas | Zoom canvas in / out (pinch gesture on trackpad also works) |
| Pinch gesture anywhere | Zooms canvas only — browser zoom is blocked app-wide |
| Ctrl + = | Zoom in |
| Ctrl + − | Zoom out |
| Ctrl + 0 | Reset zoom to 100% |
| Escape | Close any open modal (disabled during the scripted guided tour) |
| Double-click epic label | Rename epic inline |
| Right-click any card | Context menu — Edit / Duplicate / Push / Delete |
The progress bar in the topbar scores how spec-complete your map is. In Advanced mode: description + test type + edge cases per story, each worth 1/3. Hover to see exactly what's missing. Green = agent-ready.
Right-click any epic header, flow header, or story card for a context menu with Edit, Duplicate (stories only), Push to Jira, and Delete. Faster than hunting for the ✎ button.
On maps with multiple epics, a sticky strip appears at the bottom of the canvas with numbered epic pills. Click any pill to scroll that epic into view — essential on large maps.
Internal means the agent can call that service autonomously. External means the agent must stop and wait for a human. The most important field for agentic workflows — fill it in for every story that has a dependency.
Open Questions appear in the spec with a ⚠ marker. The agent is explicitly instructed to flag these and not guess. Use them to surface decisions that haven't been made yet.
A global NFR like "All API endpoints must require JWT" applies to every story in the entire spec. Set it once in Overview → NFRs. Injected above every epic in the export — the agent never misses it.
Export JSON regularly — it's your lossless backup. Preserves everything: flows, NFRs, API contracts, edge cases, open questions, dependency maps, release assignments, and Jira keys. Store it in your repo.
The tech stack drives test framework resolution in the exported spec. Without it, integration tests get a generic fallback message. Fill in Overview → Tech Stack before exporting.
A Flow is a user journey within an epic — "Registration", "Make Payment". It's a container that holds stories and provides API contract context. A Story is an atomic requirement within that flow. One flow typically has 2–6 stories. The agent implements story by story but reads the flow's API contracts for context.
Completely. Jira integration is optional. Create maps from scratch, export specs, hand to agents — no Jira connection needed.
Imported Jira stories have title and description but no edge cases, test type, or dependencies. Open each story's ✎ edit dialog and fill in the Spec tab and Dependencies tab. The progress bar shows what's missing.
Expected. Sync pulls title and description as plain text — it doesn't reconstruct flows as structured Sutra data. The content is in the description field and will appear in your spec export. For full round-trips, use Export JSON and Import JSON.
Export as JSON from the topbar. Send the file. Teammate opens Sutra → + New Map → Import → From File. Full map appears — all epics, flows, stories, spec fields, and Jira keys intact.
When you export from the Calculator map, Sutra produces a structured markdown document your agent can act on immediately. Here's what each section does:
Testable conditions the agent uses to define "done". Written in the Description field of each story. Example: "AC: Basic mode shows digits 0–9, operators +−×÷, equals, clear, and backspace."
Boundary conditions and failure modes. Example: "Division by zero returns 'Error'. Chained operations evaluate left-to-right. Negative results display with leading minus."
Structured endpoint definitions on each flow: method, path, request body shape, response codes. The agent uses these to implement the exact API surface without guessing.
Non-functional requirements injected into every story in the epic. Example: "All computation must be handled client-side. No data is sent to a server."
Internal (agent calls autonomously) vs external (agent pauses and waits for human). Prevents the agent from blocking on things it can resolve itself.
Unit, integration, or E2E declaration on each story. The agent uses this to generate the right test scaffold — Jest for unit, Supertest for integration, Playwright for E2E.
Claude Code is Anthropic's command-line agent for software engineering. It reads your project, understands context, and implements stories one by one.
Run claude in your terminal from the project root. Claude Code reads your existing codebase before doing anything.
Either paste the markdown contents directly into the Claude Code prompt, or reference the file: /path/to/calculator-spec.md.
Start with a clear instruction. A good opening:
Prompt template: "Read this spec carefully. Implement the stories in order, starting with [Epic Name]. For each story: implement the feature, write the test indicated by the test type, and confirm AC is met before moving on. Ask me if anything is ambiguous."
Claude Code will implement story by story. Review each before approving. The engineering notes in the spec tell it what's already built and what to extend vs rewrite.
If you prefer a chat interface over the command line, Claude.ai works well for smaller builds or exploring the spec.
Go to claude.ai and start a fresh conversation. Use a Project if you want Claude to remember context across sessions.
Drag the exported markdown file into the message, or paste the contents. Claude reads the full spec before responding.
Ask Claude to implement one story at a time and paste the code into your editor. This gives you more control than a fully autonomous agent run.
Single file vs project structure: Use "Single file" export for smaller features or when sharing with Claude.ai. Use "Project structure" for Claude Code — it creates one file per epic, keeping context focused per implementation session.
Engineering notes matter: The engineering notes field (in the map Overview tab) is prepended to every export. Use it to tell the agent about your stack, shared patterns, what's already built, and conventions it must follow.
Export after each release: When you export for a specific release (e.g. MVP), Sutra stamps the engineering notes with what was built. Future exports tell the agent "these stories are done — don't rewrite them."
Don't skip edge cases: The most common agent failure mode is incomplete edge case handling. An agent that sees "AC: user can divide" will implement happy path only. "AC: division by zero returns Error" changes the output entirely.
Last updated: March 2026
Sutra is a Chrome extension. This policy explains what data Sutra collects, how it is used, and how it is stored.
We collect nothing. Sutra does not collect, transmit, or store any personal data on external servers. There are no analytics, no tracking pixels, no third-party data sharing, and no accounts.
All data you create in Sutra — maps, stories, epics, flows, settings — is stored exclusively in your browser's local storage (chrome.storage.local) on your own device. It never leaves your machine unless you explicitly export it.
When you use Sutra's Jira integration, Sutra communicates directly from your browser to your Atlassian instance using your existing browser session cookies. Sutra does not store, proxy, or log your Jira credentials or API tokens. No Jira data passes through any external servers — the connection is entirely between your browser and your Atlassian instance.
Sutra requests the following Chrome permissions:
To save your maps and settings locally in your browser using chrome.storage.local.
To communicate with your Jira instance when you trigger a push or sync from the extension.
No other permissions are requested. Sutra does not access your browsing history, other tabs, or any data outside of the extension itself.
Because all data is stored locally, you have full control:
If this policy changes materially, it will be updated here and noted in the extension release notes. We will never introduce data collection without clearly disclosing it.
Questions? Reach out via the Chrome Web Store listing or the Sutra website at sutrasdd.app.