Atono — Product Map (September 24, 2026)

A semantic model of Atono for AI agents. It explains what Atono is, how its concepts relate, and the rules that govern them, so an agent can reason about Atono without re-reading the documentation. This map was built from the full Atono documentation at docs.atono.io, including its release notes and API reference. Plan availability (§11) comes from the Atono pricing page. It reflects the product as documented through the September 15, 2026 release. Release history: Feb 18 → Apr 1 → May 14 → June 29 → July 28 → Sep 15, 2026.

1. What Atono is, in one paragraph

Atono is a product development platform that connects product knowledge, work, decisions, releases, and outcomes in one system, so that people and AI tools work from the same understanding of the product. It covers a continuous loop of Plan → Build → Deploy → Measure. Planning happens through stories, epics, product themes, timeboxes, timelines, and sprints. Building happens in team workflows run as Scrum or Kanban. Deployment is controlled through feature flags attached to the stories that introduced them. Measurement comes from usage data that reports back into those same stories. The docs describe the premise in one line: "AI can accelerate work, but only when it has access to accurate context."

Product knowledge is Atono's name for where that shared context lives. It has two levels:

• The Glossary holds workspace-level context: terminology, features, roles, and workflows.
• AI context holds item-level context: the decisions, investigation findings, and implementation changes recorded on an individual story or bug.

AI tools reach both through the Atono MCP server (§6).

How to think about Atono

The useful mental model is that the story is where everything about a feature converges. A story holds the requirement (user story and acceptance criteria). It also holds the feature flag that controls the feature's rollout, the usage graph that shows whether the feature is being used, and the AI context that records why it was built the way it was and what an agent changed. A generic work-tracker model will place flags, analytics, and AI memory in separate systems. In Atono they're fields and panels on the story itself, which is why an agent reasoning about "the feature" should usually start from its story.

2. The mental model — how the pieces relate

WORKSPACE  ({name}.atono.io — name and URL are permanent)
│
├── PRODUCT KNOWLEDGE ── two levels:
│   ├── Glossary (one per workspace) ── §4.4
│   └── AI context (per story/bug) ─── §4.3
│       Both reachable over MCP (§6)
│
├── EPIC (≤100 stories; a story belongs to ≤1 epic)
│   │   title · user stories · description · tags · comments (general + text-specific)
│   │   attachments · activities · version history
│   └── STORY ◄──────────── where work, rollout, usage, and AI context converge
│       ├── Title · User story ("As a [persona], I want to [action] so that [benefit]")
│       ├── Acceptance criteria (nestable; each has a persistent URL)
│       ├── Additional content (freeform notes below the ACs)
│       ├── Size (Unsized, XXS…XXL) ── "Size it for me" (AI, §5)
│       ├── Subtasks (checklist; own 4-value status: To do / In progress / Done / Won't do)
│       ├── Feature flag ── created, applied, and configured from the story (§4.1, §9)
│       ├── Feature engagement graph ── usage of this story's feature (§4.2)
│       ├── AI context ── Design decisions · Technical investigation · Technical changes (§4.3)
│       ├── Story assistant ── conversational AI authoring (§4.7)
│       ├── Product theme · Timebox · Sprint (Scrum) · Tags · Epic
│       ├── Comments (general, text-specific, per-AC) · Attachments · Activities · Version history
│       ├── Linked items ◄──► bidirectional links to stories and bugs
│       └── Slack channel (optional) · Follow (star)
│
├── BUG (separate from stories so fixes don't disrupt planned work)
│   ├── Summary · Reproduction steps · Expected · Actual (suggested template)
│   ├── Risk rating = Probability × Impact (1–25) ── "Rate it for me" (AI)
│   ├── Reporter · Affected environments · Tags · Timebox · Sprint
│   ├── AI context ── Technical investigation · Technical changes (no Design decisions)
│   └── Subtasks · comments · attachments · activities · version history · linked items
│       (bugs have no size and no product theme)
│
├── TEAM (≤50 per workspace, ≤50 members each)
│   ├── Methodology: Scrum or Kanban · Access: Public or Private
│   ├── WORKFLOW (4–25 steps in 4 fixed categories, §3)
│   ├── Backlog management (optional; backlog owners, ≤10)
│   ├── Team time zone (default US/Pacific) · Cycle time window (default 6 months)
│   └── Team overview → Analytics tab (§7) · Team members tab
│
├── INTAKE LANES (fixed, non-customizable, §4.6)
│   ├── Story refinement ── unassigned stories
│   └── Bug triage ── untriaged bugs
│
├── PLANNING OVERLAYS
│   ├── Product theme ── strategic grouping; stories only
│   ├── Timebox ─────── dated group of stories and bugs; an item is in ≤1 timebox
│   ├── Timeline ────── visual schedule of timeboxes and releases
│   ├── Sprint ──────── Scrum teams only; non-overlapping, per team
│   ├── Release ─────── a dated marker, global to the workspace
│   └── Tag ─────────── key:value label; the only overlay spanning stories, bugs, and epics
│
├── ENVIRONMENTS (defaults dev / test / stage / prod) ── scope flag configuration,
│   bug "affected environments", and usage data; each has an environment key
│
└── ENGAGEMENT page ── top 10 features by usage across the workspace (§4.2)

The most important relationship is that the story is where work, rollout control, usage outcome, and AI context meet (§1).

The one agents most often get wrong is Product knowledge. It isn't a single container; it names two things at two levels. Asked "what is Product knowledge in Atono," the correct answer names both the Glossary and AI context.

3. The four workflow categories (universal spine)

Every story and bug on a team moves through that team's workflow. Each workflow step belongs to one of four fixed categories. Teams can customize the steps, but not the categories.

Rules an agent should know:

• Step count and properties: A workflow has 4–25 steps. Each category needs at least one step applicable to stories or bugs. Steps have a name, color, order, and applicability (stories, bugs, or both).
• Who can customize: Team admins and workspace Administrators can customize a workflow, and can restore it to the default of 7 steps (To do, Design, Development, Test, Review, Done, Won't do).
• Non-linear movement: Items can move backward and skip steps.
• Recategorizing a step: Time spent in a step is recorded against its category at the moment the item leaves. So recategorizing a step affects only time spent after the change, and history isn't rewritten.
• What Won't do is excluded from:
  • The epic progress bar and its story count.
  • The subtask progress meter (for subtasks marked Won't do).
  • Sprint totals, burndown, and velocity.
  • Cycle time display.
  • Estimated completion dates.
• Scope boundary: These rules govern team workflows only. Story refinement and Bug triage (§4.6) have their own fixed steps and sections, and none of the rules above apply to them.

4. The distinctive concepts (what makes Atono not Jira)

These are the parts a generic work-tracker model will get wrong.

4.1 Feature flags live inside stories

• Where flags are managed: A flag is created or applied from a story's details panel, and configured by clicking its name there. The Feature flags page gives the same control across all flags. Creating a flag from a story links it to the feature automatically.
• Who can create and apply: Anyone can create a flag, and anyone can apply an existing flag to a story they can access. The creator becomes the flag's Owner.
• Flags across stories: One flag can be applied to several stories, which is intended for work that extends an existing feature. Applying a flag that's already On in some environment immediately enables that functionality there, and Atono warns first. The docs don't state whether a single story can carry more than one flag; the API and MCP both expose one flag per story.
• Team permissions from the backlog: When a flagged story is added to a team's backlog, that team automatically gets flag User permissions, but only if no other team already has them (§9).
• Status is about deletion safety: Flag status is framed around one question, "is this flag safe to delete?" The model treats flags as having a lifecycle tied to the work that introduced them (§9).
• Code side: Developers still add the flag to application code using an Atono SDK. The flag's configuration screen offers code samples for JavaScript, React, and Java.

MCP reachability: only partial. atono_get_story returns the name of the story's flag, but not its On/Off state. No MCP tool creates, configures, or toggles flags. The REST API can read flags and set an environment On or Off (§12).

4.2 Feature engagement lives inside stories

• Where the graph appears: When usage tracking is set up, the story shows a Feature engagement graph. It's available for a story that's assigned to a team and is in an In progress or Done step.
  • While the story is in progress, the graph sits below the ACs and attachments.
  • Once the story is Done, the graph moves to the top of the story.
• Views and graph types: The Top customers view (the default) ranks up to 10 customers as a bar chart, or as a line graph over time. The Environments view compares usage across environments. The timeframe runs from 1 to 60 months, with daily points under a year, weekly points over a year, and about 400 points at most.
• Unattributed usage: Events without a customer value appear as Unknown.
• Default environment: The default environment filter is the last environment listed on the Environments page, so the order of that page matters.
• Per-user settings: Hiding the graph and the graph's view settings are saved per user. Hiding it doesn't stop data collection.
• Stopping and clearing data:
  • Removing a click mapping stops new data for that action but keeps history.
  • Clear data permanently deletes all historical usage for the story, for everyone.
• The Engagement page: It ranks the top 10 features (stories) by usage across the workspace. It can be filtered by product theme, completion date, team, environment, customer, and location, and defaults to the last 3 months in the last-listed environment.

Usage can reach Atono in two ways:

1. Code: A developer calls record('STORY-123') from an Atono SDK. That can be Web or React (version 1.1.0 or later for usage), or Java or Node.js on the server (§9).
2. Mapped clicks: Anyone can use the Chrome extension to map clicks on page elements to a story, with no code changes (§12). This still requires the Web or React SDK to be running in the browser, and it can't capture actions that happen only on the server.

MCP reachability: none. No MCP tool reads usage or engagement data.

4.3 AI context is a first-class field

AI context is the item-level half of Product knowledge: a section on a story or bug where AI tools and people keep context that has to outlive a single session.

Rules:

• How it's written: AI context is written mainly through the MCP server (atono_update_ai_context). It can also be edited in the web app, and it only appears on an item once at least one tab has content.
• Read before write: Agents must call atono_get_ai_context before atono_update_ai_context, then write a synthesized version. They shouldn't simply append or prepend. When an agent retrieves an item through MCP, it's prompted to read its AI context first.
• Design decisions on new stories: After atono_create_story, the agent is prompted to record design decisions immediately. Asking for this explicitly is the more reliable way to make sure it happens.
• Version history:
  • Each tab has its own version history, separate from the item's content version history.
  • A sparkle (✦) marks versions created by an MCP tool.
  • Versions can be restored or deleted.
• Story assistant: The Story assistant (§4.7) writes design decisions into this field. That's how rationale from authoring reaches coding agents.
• Plan availability: AI context is a 30-day trial on the Free plan (§11).

4.4 The Glossary (one half of Product knowledge)

• Scope and entries: There's one Glossary per workspace, shared by everyone. Each entry is a Concept with a unique name, a Definition, Synonyms, and Related concepts.
• Building from documentation: Atono crawls documentation URLs. Root-level URLs give better coverage than single articles. A build may take up to 20 minutes, runs in the background, and notifies you when it finishes. Adding a product name reduces ambiguity when the name is also a common word.
• Building from a file: You can upload a TSV instead. It must be 1 MB or smaller and have the columns Concept, Definition, Synonyms, and Related concepts. On import, definitions are truncated to 500 characters, duplicate concepts are skipped, and unknown related concepts are flagged. Warnings appear on the Sources tab.
• Refreshing: A refresh reprocesses documentation sources.
  • It adds new concepts, updates existing ones only when the source clearly supports the change, and removes concepts that no longer apply.
  • Manual edits are blocked while it runs.
  • A Glossary built from a TSV can't be refreshed; you delete it and rebuild from an updated file.
• Deleted concepts: They move to a Deleted concepts page. They're excluded from future refreshes until someone restores them, and adding a concept with the same name prompts a restore instead.
• History and undo:
  • A History tab records every addition, edit, and deletion, with its source: AI, Upload, or User.
  • Changes can be undone individually or in bulk. Only the most recent change to a given concept can be selected for undo.
  • An entire refresh can be undone only if it's the most recent refresh and nothing has changed since.
  • Each concept also has its own version history.
• Navigation: An alphabetical jump bar (with a # section) stays visible while scrolling, and the Glossary can be searched by name or description.
• Export: The Glossary exports as TSV for AI tools that don't connect to MCP.
• Stated purpose: AI tools produce output that sounds right but gets details wrong without product context, especially when product terms overlap with everyday language.

MCP reachability: read-only. atono_get_glossary returns the whole Glossary as TSV. No MCP tool edits it. Permissions are covered in §8, limits in §10, and plan availability in §11.

4.5 Ask Capy

• What it is: An AI assistant that answers plain-language questions using completed stories and bugs from public teams, and links to its sources. Capy is the capybara mascot.
• Where it is: Ask Capy opens from the workspace header, next to Search.
• Release status: It's in limited release; workspaces request access through Atono support.
• What it can't see: Private-team work and unfinished items.
• Conversation memory: A conversation keeps context for up to one day, and "Start a new conversation" clears it.
• Gates and quota: §5 and §10.

MCP reachability: none.

4.6 The two intake lanes

Unassigned work doesn't sit in a generic backlog. It goes to one of two purpose-built lanes, whose steps can't be customized (see the scope boundary in §3).

Story refinement

• Access: It's open to everyone in the workspace.
• Steps: Idea → Refinement → Ready for assignment → Won't do. Items can be created in any step except Won't do.
• What isn't tracked: Sizing, estimated completion dates, cycle time, and staleness.
• Entering and leaving: Stories arrive here when they're created without a team, unassigned from a team, or imported without a matchable team. Assigning a story to a team moves it to the bottom of that team's To do.

Bug triage

• Sections: Reported bugs, More info required, and Won't do.
• When a bug counts as triaged: It needs both a team backlog and a risk rating. Then it leaves triage and goes to the bottom of the team's To do. Setting either Probability or Impact to "Not selected" sends it back to Reported bugs.
• More info required: Moves the bug to that section and assigns it to the reporter.
• Reject: Moves the bug to Won't do.
• Old bugs: A bug that has spent more than 7 consecutive days in its current stay in triage shows a red clock. The Bug triage menu item also shows a badge.
• Subtasks: They aren't shown in the triage view.

4.7 The Story assistant

A conversational AI that turns a discussion of what you want to build into a story title, user stories, and acceptance criteria.

How you start

• From an existing story: Click Story assistant in the story.
• From scratch: Choose Create new → Create with AI and describe what you want. Atono generates a title and opens the story and the assistant side by side, with the user story and ACs left empty until the conversation fills them in.
• Guided mode: "Guide me through it" asks structured questions using quick-pick cards. Questions can be single or multiple answer, and you can skip them, answer "Other", or navigate back.

Context it reads

• The story's current content.
• The story's epic, the epic's goal, and peer stories in the epic.
• The workspace Glossary.
• The story's existing design decisions.
• Other stories you reference by ID, up to 10 per message. The docs describe the assistant using their titles, user stories, acceptance criteria, and additional content.

If the workspace has no Glossary, the assistant says so and links to build one. The docs call the Glossary the thing that grounds suggestions "in your product rather than generic assumptions".

What it produces

• User stories: It reuses workspace personas where they fit, and can introduce a new persona that's created when you accept.
• Acceptance criteria: A complete suggested set, which may add, rewrite, reorder, split, or remove criteria.
• Titles: It may suggest a new title when scope changes, and may decline a requested title that doesn't fit the story's scope.

Staged, not applied

• Preview: All suggestions sit in a preview over the story, where you can edit them directly.
• Show changes: Switches to a read-only redline of additions and removals across the title, user story, and ACs. Hide changes returns to the editable preview.
• Accept or reject: Accept changes applies everything; Reject discards everything, with a brief Undo.
• Undo of the latest AI change: Undo (and Redo) reaches only the most recent AI change. It stops being available after another AI change or a manual edit.
• Leaving the story: Navigating away with unapplied changes prompts for confirmation. Closing just the assistant panel keeps the preview.
• Long conversations: They may be summarized, with a marker showing where the summary begins.

Writing back

Rationale, tradeoffs, and scope decisions from the conversation are added to the story's Design decisions when you accept. You can also ask the assistant to save a specific decision. Those decisions then become available to other AI tools over MCP (§4.3).

Attribution

Changes stay attributed to the person driving the conversation. A sparkle (✦) with the tooltip "Performed by Story assistant" marks them.

MCP reachability: none. The assistant itself isn't callable over MCP, but its design decisions are readable through atono_get_ai_context. Plan availability is in §11.

4.8 Tags

• What a tag is: A key:value label, such as Component: api. Tags are the only grouping that applies to stories, bugs, and epics alike.
• One value per key: An item holds one value per key, so applying a second value for a key replaces the first. When bulk-adding, Atono warns before replacing. Size limits are in §10.
• Case: Keys and values are case-insensitive but keep the casing they were created with.
• Applying and removing: Anyone can apply and remove tags. By default anyone can also create keys and values, but Workspace Owners and Administrators can restrict creation:
  • Only selected users create keys, or
  • Only selected users create keys and values (each granted "Keys and values" or "Values only").
  • Owners and Administrators can always create both.
• The Tags page (Owners and Administrators):
  • Create a tag with a description and multiple values.
  • Rename a key, which updates it on every item.
  • Edit values.
  • Set how values are ordered when applying: alphabetical, most recently applied, or custom.
  • Delete a value or a whole tag, after seeing how many items are affected. Deleting a tag's last value deletes the tag.
• Where tags show up:
  • Everything supports tag filtering (include, exclude, or any value of a key), a Tags column, and bulk add and remove.
  • Search indexes tag values.
  • Tag changes appear in an item's Activities under Type: Tag.
• Private-team items: Tags can be added to or removed from private-team items through Everything even by users who aren't members of that team.

MCP reachability: none.

4.9 Epics as a working surface

• What an epic holds: An epic groups up to 100 stories under a shared goal, and each story belongs to at most one epic. It has a title, epic-level user stories, a description, an ordered list of stories (each showing its team and workflow step), tags, attachments, comments, and an Activities list.
• Progress: The progress bar and story count exclude Won't do stories.
• Adding stories:
  • Create stories inline by title, add existing stories from the epic, or add from a story's details panel.
  • Bulk-add from Everything, where select-all works on lists of 100 or fewer.
  • Adding a story that's already in another epic moves it, after a warning.
• Everything integration: Everything has an Epic column and an Epic filter, which can include stories with no epic. Turning on the filter shows the column automatically. The filter mainly exists for bulk actions, such as adding an epic's stories to a timebox or product theme in one pass.
• Search: Search can also filter by epic.
• Comments: Epics take general comments and comments on specific description text, with @mentions and accept or reject. AC-level comments exist only on stories.
• Version history: An epic's history is opened by clicking a content update in its Activities. The header menu option that opens history for stories and bugs doesn't exist for epics.
• Splitting a story in an epic: The epic page says both resulting stories stay in the epic. If the story has no epic, you're offered the chance to create one.
• Deleting an epic: Removes the grouping only. Its stories stay on their backlogs.

MCP reachability: yes, for create, read, list, retitle, description, user stories, and adding or removing stories (§6). Epics can't be deleted over MCP. Epic titles must be unique across the workspace.

5. AI features and their gates

Most AI features only turn on once there's enough data for their output to be trustworthy. So "the feature isn't working" usually means a threshold hasn't been met.

Hard gates — the feature is unavailable until the condition is met

Soft gates — the feature runs, but quality degrades

No gate stated

Announced, not shipped

Attribution: A sparkle (✦) marks AI-suggested values, such as an applied AI size or risk rating, and actions taken by an AI actor. MCP actions show "Performed by MCP server" and Story assistant changes show "Performed by Story assistant". In both cases the human who drove the action stays the attributed author.

6. The MCP server — how agents actually use Atono

The Atono MCP server runs locally in Docker and connects MCP-enabled tools to a workspace. The docs give setup steps for Claude Code, Claude Desktop, Cursor, OpenAI Codex, VS Code (GitHub Copilot), and Windsurf.

Command: docker
Args: ["run", "--pull=always", "-i", "--rm", "-e", "X_API_KEY", "atonoio/atono-mcp-server:latest"]
Env:  X_API_KEY=YOUR_ATONO_API_KEY

• Prerequisites: Docker Desktop 27.0 or later, which must be running whenever the server is used. You also need an Atono API key and an MCP-enabled tool.
• Updates: Restarting the AI tool pulls the latest image, because the config uses --pull=always.
• Whose permissions: The server acts as the user who owns the API key (§12).
• Scope: It exposes only the actions Atono defines and can't reach data outside the workspace.

The 42 tools

This list sums to 42 and matches the Atono MCP tools page.

• Setup & context (5) — atono_configuration, atono_list_users, atono_list_teams, atono_get_team_workflow, atono_get_glossary
• Stories (10) — atono_get_story, atono_list_story_personas, atono_create_story, atono_update_story_title, atono_update_story_content, atono_update_story_ac, atono_update_story_additional_content, atono_update_story_team, atono_update_story_step, atono_update_story_assignee
• Bugs (7) — atono_list_environments, atono_get_bug, atono_create_bug, atono_update_bug, atono_update_bug_step, atono_update_bug_assignee, atono_document_bug_fix
• Linked items (1) — atono_link_bugs_or_stories
• Subtasks (4) — atono_get_subtasks, atono_create_subtask, atono_update_subtask, atono_delete_subtask
• Epics (8) — atono_create_epic, atono_list_epics, atono_get_epic, atono_update_epic_title, atono_update_epic_description, atono_update_epic_user_stories, atono_add_story_to_epic, atono_remove_story_from_epic
• Attachments (3) — atono_upload_file_url, atono_create_attachment, atono_get_attachment
• Timeboxes (2) — atono_list_timeboxes, atono_list_timebox_items
• AI context (2) — atono_get_ai_context, atono_update_ai_context

What MCP can and can't reach

Agent cautions

• Tools that replace rather than append:
  • atono_update_story_ac replaces the whole AC list. Always fetch the story first so existing criterion IDs can be preserved. Omitting a known ID creates a new criterion in its place, which permanently loses that criterion's comments, attachments, and usage metrics.
  • atono_update_epic_user_stories, atono_update_epic_description, and atono_update_story_additional_content also replace their content in full.
  • atono_update_bug replaces any field it's given. To add one affected environment, pass the whole list.
• Where new stories land: atono_create_story without a team puts the story in Story refinement.
• Required bug fields: atono_create_bug requires a title, summary, reproduction steps, expected behavior, and actual behavior. The agent infers any the user doesn't supply.
• Attachment URLs expire: Those returned by get_story, get_bug, and get_attachment expire quickly, so re-fetch the item to get fresh ones.
• Removing from an epic: atono_remove_story_from_epic returns an error if the story isn't in that epic.
• Irreversible changes: Some changes, such as updating ACs or moving steps, write directly to Atono and may not be reversible.
• API keys: Treat them as passwords and never commit them.

7. Metrics — exact definitions

Agents get these wrong by assuming industry-standard definitions. Atono's are specific.

Cycle time

• Definition: The cumulative time an item spends in the In progress category of a specific team's workflow. It starts on To do → In progress, stops on reaching Done, pauses when the item leaves In progress, and resumes when it returns.
• Weekends: Nights and weekends count, by design. Cycle time isn't editable.
• Changing teams: Cycle time is tracked per team. Moving an item to another team starts it at zero there. Moving it back restores the time accumulated with the original team.
• Creating in progress: You're prompted for the date and time work began.
• When it's unavailable: Before an item first enters In progress, while it's back in To do (it reappears on re-entry), for Won't do items, and for outliers.

Cycle time window

• Purpose: The history Atono uses for team averages.
• Options: Default is items completed in the past six months, or as far back as records go. Alternatives are a rolling 1–12 months, or everything from a chosen date.
• What it feeds:
  • Estimated completion dates.
  • Staleness.
  • The size used for unsized stories in totals.
  • The throughput projection.
• Who can set it: Workspace Owners, Administrators, Backlog Owners, and Team Admins.

Outliers

• Effect: Items manually excluded from average cycle time, cycle time reports, staleness, and estimated completion dates.
• Who can mark them: Workspace Owners, Administrators, Backlog Owners, and Team Admins.

Staleness indicator (hourglass)

An item is flagged as stale when all of these hold:

• Its time in its current In progress step (re-entries count) exceeds three times the standard deviation for similar items.
• At least five historical items of the same type and size exist. Unsized counts as its own size.
• The item isn't an outlier.

Averages are specific to the team and the step, come from completed items in the cycle time window, and are grouped by item type and, for stories, size. Changing an item's size affects the historical calculations.

Snoozing: Team admins and workspace Administrators can snooze the indicator for 1 day, 1 week, 1 month, or until changed. A snooze hides it for everyone, applies only to the current step and team, and resets when the item changes step or team.

Story points

Sizes map to Fibonacci points: XXS=1, XS=2, S=3, M=5, L=8, XL=13, XXL=21.

Unsized stories are handled differently depending on where the number appears:

How filters affect totals:

• On In progress pages, totals reflect only the visible items.
• Sprint totals on the Scrum backlog always reflect the whole sprint.
• Everything shows a total only when it's filtered to a single team and the Story size column is visible.
• Timeline totals require a single-team filter. A timebox detail view shows a total when all its items belong to one team.

Estimated completion dates (Kanban)

Atono estimates a completion date for each item in To do in four steps:

1. Compute average cycle time over the cycle time window.
2. Derive daily throughput.
3. Compute separate averages for bugs versus stories, and for each story size including Unsized. A size with fewer than five stories falls back to the general story average.
4. For each To do item, sum the estimated cycle times of the items ahead of it, divide by throughput, then add the item's own projected cycle time.

• Live updates: Dates recompute as the queue is reordered.
• Warnings: A date shows orange when it falls after the end date of a timebox the item belongs to.
• Filters: Dates stay visible when filters are applied in the Kanban Backlog and In progress views. Reordering under filters is still blocked (§13).
• Exclusions: No estimate is given for outliers.
• Personal setting: Each user can hide the dates.

Timebox projected completion

For Kanban items already in progress, the projection is based on when the item entered In progress plus the team's average cycle time. For Scrum items, it reflects sprint timing: Unscheduled, or a sprint that ends after the timebox.

Velocity and sprint capacity projection (Scrum)

• Velocity: Story points completed per sprint.
• Projected capacity: Average velocity of completed sprints, converted to a daily rate and multiplied by the sprint's calendar days, weekends included. It needs at least two completed sprints.
• Over capacity: Planned points above projected capacity show in orange on the backlog, and as an overfill segment on the Sprint calendar.

Burndown (Scrum)

• Axes: Story points remaining against sprint dates. Burndown is available for active and completed sprints only.
• Four lines:
  • Guideline: Ideal linear path from full scope to zero.
  • Actual: Points remaining at the end of each day.
  • Scope: Total points in the sprint each day. Hovering lists the stories added or removed that day, including moves to Won't do.
  • Projected: Active sprints only.
• Projected line: A best-fit regression that appears after three full days of data. The start date doesn't count.
• Projection details: The verdict (on track, ahead, or behind, in whole days rounded down) needs the sprint to be at least half over by calendar time and at least two completed sprints.
  • Ahead: suggests stories to pull in, taken first from the next sprint's To do order, then later sprints, then Unscheduled.
  • Behind: lists stories unlikely to finish.
• Scope changes:
  • Changes on the first day count as starting scope.
  • Changes after a sprint ends don't alter its historical burndown.
  • Changing a completed sprint's dates recalculates it.
• Time zone: Days are grouped by the team time zone.

Team Analytics (Team overview → Analytics tab)

Story throughput

• What it shows: Stories or story points completed per week, month, or sprint. Sprint view shows only complete sprints.
• Summary values: A total and a per-period average, plus a trend line.
• Counting rule: A story counts in a period when it reaches Done and stays there through the end of that period.
• The current period: It shows completed-so-far plus a projection, which is the average completed per period in the cycle time window. It's excluded from the average and the trend. Never report the projection as delivered work.
• Drill-down: Selecting a bar opens Everything filtered to those stories. Non-members can't open a private team's stories.

Cycle time by workflow step

Average cycle time split across the team's In progress steps, in rows per story size plus a row for bugs. This is the only place cycle time is attributed to individual steps. Steps can be hidden from the legend.

Cycle time over time

Average cycle time per period for stories (split by size) and bugs combined. The bar granularity depends on the range:

Shared behavior across the reports

• Data outside the cycle time window appears dimmed, with dashed lines marking the calculation range.
• Selecting a bar or segment opens the underlying items in Everything, with outliers excluded.
• Periods follow the team time zone.

8. Roles and permissions

Roles are additive; a user can hold several, and the permissions stack. No user can remove a role from themselves.

Workspace roles

Workspace Owner

• Changes the plan and billing.
• Adds or removes Owners.
• Deletes the workspace.
• Otherwise has the same abilities as an Administrator.

Administrator

• Manages workspace settings and environments.
• Enables integrations.
• Manages and deletes users, and assigns Administrators and Product Managers.
• Edits or deletes other users' comments.
• Marks outliers.
• Can create tags, restrict tag creation, and manage the Tags page.

Product Manager

• Manages product themes (see the first trap below).
• Adds and removes backlog owners.
• Accesses and manages the backlog of any team, public or private.
• Adds members to any public team.
• Assigns other Product Managers.
• Has Owner-level Glossary rights.

Standard User (the default)

• Creates teams and joins or adds members to public teams.
• Manages public backlogs that have no backlog owner.
• Creates, edits, and deletes bugs.
• Comments, and accepts or rejects comments.
• Creates and applies feature flags.
• Triages bugs.
• Views and exports the Glossary.

Team roles

Team member

• Is granted automatically on joining.
• Edits the team's name and description.
• Manages the team's Slack channel.
• On a private team, can access the backlog.

Team admin

• Doesn't need to be a member of the team.
• Edits team details and deletes the team.
• Changes the team's access type and methodology.
• Manages admins and backlog owners.
• Customizes the workflow.
• Marks outliers.
• Can't remove themselves, and the last admin can't be removed.

Backlog owner

• Doesn't need to be a member of the team. A team can have up to 10.
• Manages upcoming stories: creating, adding, reordering in To do, deleting, and moving in or out of Won't do.
• On Scrum teams, owns sprint planning.
• Marks outliers.

Any user with access to a team's backlog can add or remove team members. Private teams are visible only to members, team admins, backlog owners, and users with higher workspace roles.

Two conditional-permission traps

These reverse depending on whether anyone holds the role.

1. Product themes: If no Product Manager exists, anyone can create, manage, and apply product themes. Once at least one exists, only Product Managers can.
2. Backlog management: This is a per-team setting that takes effect once backlog owners are assigned. Other users without an overriding role can then only move stories out of To do and reorder In progress. They can't create or delete stories, can't split stories, can't move stories in or out of Won't do, can't manage sprints, and can't assign stories to that team. Bugs stay open to team members either way.

Independent permission tiers

Feature flags

• User: Toggles and configures the flag, defines slices, and grants User permission to others.
• Owner: Everything a User can do, plus renaming the flag, removing it from a story, deleting it, and granting Owner permission.
• Workspace Administrators: Can also edit, delete, and change permissions on any flag.
• Constraints: Nobody can modify their own permissions. The last Owner and last User can't be removed.
• Team permissions: Once a team has flag permissions, they're never revoked automatically. A team whose permission was removed manually won't regain it automatically.
• Viewing: Everyone can view flags.

Glossary

• Contributor: Adds, edits, deletes, and restores concepts.
• Owner: Everything a Contributor can do, plus refreshing and deleting the Glossary and managing Glossary permissions.
• Who gets Owner-level rights automatically: Whoever builds the Glossary, plus Workspace Owners, Administrators, and Product Managers.
• Everyone else: Read-only, and can't see the History tab or version history.

9. Feature flags — the full model

Naming

Flag names must be unique. They must start with a lowercase letter or underscore and contain only lowercase letters, numbers, and underscores. Length is in §10.

Statuses, framed around deletion safety

The Feature flags page summarizes each flag's configuration as ON, OFF, or Mixed. It also shows when the flag was last evaluated and how long it has served its current value, for example "ON for 8 hours".

Configuration

• Basic configuration: On or Off per environment. This is only available when no slices exist.
• Slices: Override an environment's default value for a subset of traffic.
  • Each slice has up to two conditions, one Customer and one Location, combined with AND.
  • Slices are evaluated top to bottom. The first match wins, so slice order matters.
• Customer conditions: Operators are is, is not, contains, does not contain, is one of, and is not one of. Values are case-sensitive, up to 255 characters, and can be picked from values the SDK has reported.
• Location conditions: Operators are is in and is not in, over continents, countries, subregions, and states or provinces. ISO codes are searchable. Location comes from the request IP, so it can be inaccurate, for example on a tethered cellular connection.

Three ways a flag's slices get silently deleted

1. Bulk-configuring flags On or Off from the Feature flags list deletes the slices in each changed environment.
2. Setting a flag's environment configuration through the REST API (on or off) removes all slices for that environment.
3. Flipping a flag with the Chrome extension in a single-tenant environment replaces all slice configurations with one environment-wide value. The extension warns first.

Renaming, deleting, and code references

• Renaming or deleting a flag: If code still references the old name, the SDK can't find it, uses the fallback value in the code, and logs an error.
• Deleting a flag: The flag is removed from every story first, and bulk deletion isn't supported.
• Renaming an environment: The environment key doesn't change.

SDKs

The SDKs are based on OpenFeature.

Initializing:

• Web and Node.js: Atono.fromEnvironmentKey(key)
• React: <AtonoProvider environmentKey=…> plus useFeatureFlag() and useUsageReporter()
• Java: Atono.builder().build(key)

Evaluating: getBooleanValue('flag_name', fallback)

Evaluation context:

• Web and React: Detect location automatically from the user's IP. Set the customer with setContext() (Web) or evaluationContext on the provider (React).
• Java and Node.js: Don't store context globally. Pass it with each evaluation and each record() call. Location comes from getLocationProvider().fromClientIp(ip) in Java and getLocationService().fromClientIp(ip) in Node.js.
• IP addresses: Pass the client's IP, not the server's. IPv4 and IPv6 are supported. An unresolvable IP means the evaluation proceeds without location.

Runtime behavior

• Snapshot: At startup the SDK fetches a snapshot of all flags and slices into memory, and evaluations happen locally.
• Polling: The SDK polls for updates every 5 seconds by default. This is configurable, and polling can be disabled.
• Losing connection: If Atono becomes unreachable after startup, the SDK keeps using the last configuration.
• Fallback: If the SDK can't load a configuration at startup, or the flag doesn't exist, it returns the fallback value. Use the same fallback everywhere a flag is checked.
• Evaluation events: These are queued and sent periodically. They feed "Last evaluated" and customer suggestions for slices, and they can be lost if the app shuts down before sending.
• HTTP timeout: 2 seconds by default.
• Other configuration:
  • Location configuration is available in the Web and React SDKs only.
  • Logging configuration is available in the Web, React, and Node.js SDKs.
• Error codes: CLIENT_ERROR, INVALID_KEY, NOT_FOUND, SERVICE_ERROR, SERVICE_TIMEOUT, SERVICE_UNREACHABLE.

10. Hard limits and constants (quick reference)

This is the single home for numeric limits. Plan-dependent values are in §11.

ID scheme: IDs are sequential per type: STORY-123, BUG-456, EPIC-789. A deleted number is reused only if it was the highest number of its type. IDs mentioned in item bodies, comments, and activities render as clickable pills. A pill is a reference, not a link.

11. Plan availability

Plan availability isn't covered in the Atono documentation. This section comes from https://atono.io/pricing as of September 24, 2026. Check the live page before quoting it to a customer.

There are three plans:

• Free: Up to 25 users, $0, no expiration.
• Starter: $19 per user per month.
• Growth: $39 per user per month.

MAU counts unique users who hit at least one flag evaluation in a calendar month. Users are counted, not requests.

Not stated: The pricing page doesn't name the team Analytics tab or the Java and Node.js SDKs individually. Its rows for cycle time reporting and for "SDK (feature flags)" are marked on every plan.

Also note:

• Ask Capy: Although it's listed as a plan feature, it's still in limited release (§4.5).
• MCP on Free after the trial: The MCP server is on every plan, but AI context and the Glossary are 30-day trials on Free. An agent connected to a Free workspace after the trial may find the tools present but the context they fetch unavailable. That's a licensing state, not a bug.
• Reducing seats: When a plan's seat count drops, users above the limit are deactivated automatically, most recently added first. Pending invitations beyond the limit are canceled.

12. Integrations, and what a new workspace contains

Slack

• Enabling: A Workspace Owner or Administrator enables Slack for the workspace. Users then connect their own accounts from their profile or the Home page.
• Channels: Channels can be linked to teams and stories, and several teams or stories can share one channel.
• What Atono posts:
  • Channel added to or removed from a team.
  • Member joins or leaves the team.
  • Channel connected to or disconnected from a story.
  • Flag added to or removed from a story.
  • Flag turned On or Off per environment.
  • Slices updated.
  • Flag renamed.
• Flag notifications: These can be turned off per environment and are on by default, including for new environments.
• Disabling: Users have to reconnect their accounts and channels after the integration is re-enabled.

GitHub

• Enabling: A Workspace Owner or Administrator enables GitHub and chooses which repositories to include.
• How PRs are linked: Atono detects item IDs in the PR title, description, and branch name, which are always checked. Comments and commit messages are checked only if enabled.
• What appears in Atono: Each item shows a PR count plus its 6 most recent PRs, with status and build status. PR events appear in Activities.
• What Atono writes back: It posts a comment on each linked PR that links back to the item.
• Sync timing: Changes may take up to 12 hours.
• Historical PRs: PRs from before the integration was enabled, or from while it was off, are picked up only when new activity happens on them.
• Stale links: Links from a previous GitHub organization, or to a deleted repository, remain in place.

Chrome extension

• Reporting bugs: It files bugs with automatic context: URL, operating system, browser, viewport, and console and network errors attached as .txt files.
• Flipping flags: It flips flags for the current environment and customer only. In multi-tenant apps it targets or creates the customer's slice. In single-tenant apps it replaces all slices (§9). You need flag permissions to flip.
• Mapping clicks: It maps clicks on interactive elements to stories.
  • id is the preferred attribute to identify an element.
  • Every element sharing the chosen attribute is counted.
  • Clicks that reload the whole page may not be recorded.
  • Mappings are removed from the story's Feature engagement settings.
• Required meta tags: <meta property="atono:environment" content="<environment key>"> on every page, plus atono:tenancy for multi-tenant apps.
• How multi-tenant is detected: An environment counts as multi-tenant if any flag in it has a Customer slice, even an inactive one. In that case a missing tenancy tag blocks both flag flips and bug reports.

REST API

• Base URL and authentication: https://api.atono.io/api/v1/, with the header X-API-KEY.
• Keys and permissions: Keys are per user and act with that user's permissions. Actions appear as that user, with the source API. A 404 can mean the item is private to that user.
• Format: The API follows JSON:API conventions.
  • Pagination uses page[size] (maximum 100) and either page[number] (starting at 0) or page[offset].
  • Loosely-typed values are coerced. For booleans, any string other than "true" counts as false.
  • Content accepts limited HTML and no Markdown.
• Resources:
  • Stories, bugs, users (including invite), and teams (including time zone and backlog management).
  • Feature flags: read, list, and read or update environment configuration. An update is On or Off only and removes that environment's slices.
  • Workflow steps.
• Story updates: A story can be updated with its title, user story, additional content, ACs (replaced as a set), assignee, team, workflow step, linked items, and epic.
• Limits: Rate limit and page size are in §10.

Imports

Workspace Owners and Administrators can import from:

• Jira: Uses Jira Cloud through the API, with three user scopes:

  1. Issues and teams only.
  2. Issues, teams, and users involved in those issues.
  3. Everything in option 2, plus all members of imported teams.

  Options 2 and 3 need a user export CSV.

• Linear: Uses a CSV export.

Both imports

• Teams: Matched by name, case-insensitive. Unmatched teams are created as public (up to the 50-team limit), with the importer as team admin and no members. Imported teams use Kanban.
• Private teams: To keep a team private, create a private team with the matching name before importing.
• Items without a team: Stories go to Story refinement and bugs to Bug triage's Reported bugs.
• Users: Unmatched users are created as inactive with a "Not invited" status. An email address can belong to only one Atono workspace.
• External ID and re-imports: The original key or ID is kept as the External ID. Re-imports can skip items already imported.

Jira mapping

A Jira status that matches a step name, case-insensitive, goes to that step instead.

Linear mapping

New-workspace onboarding

• Sample data: New workspaces include stories, bugs, teams, epics, timelines, releases, and feature flags, so the tours have realistic objects to work with.
• Checklist and tours: The Home page has an onboarding checklist tailored to a chosen role. It launches interactive tours on stories, bugs, work in progress, Scrum and Kanban planning, timelines, and feature flags. Changing the role changes the recommended set.
• Hiding onboarding: You can hide the sample data and bring the onboarding tools back later. The Help menu, in the lower left, collects the documentation, the Atono Community Slack, and a control to restart onboarding.
• Invited users: A guided setup conversation captures their name and role. Team leads can create a first team and invite teammates during it.
• Signing in: Atono uses passwordless email links, or SAML SSO on paid plans (§11).

13. Gotchas an agent will otherwise get wrong

• Atono doesn't validate agent changes. What ships is context supply (Glossary and AI context) plus an attribution trail (✦, Source filters, version history). Nothing checks, gates, or approves changes an agent makes. Story review (§5) is announced, not shipped, and even then reviews one story's own quality rather than a change.
• Sample data isn't real work. Read over MCP or the API, sample stories and bugs look like real items. Before drawing conclusions about what a team is doing, establish whether the sample data is still present.
• Three paths delete flag slices silently. Bulk configuration, the API, and a single-tenant Chrome extension flip all do it (§9).
• MCP reads flag names, not flag state. atono_get_story returns which flag gates a story but not whether it's On. Check the UI or the REST API.
• MCP can create links but not read them. An agent can't see an item's existing linked items over MCP.
• Replace-style MCP tools lose data. An AC update that omits a criterion ID permanently loses that criterion's comments, attachments, and usage metrics (§6).
• Private work is hidden in some places and redacted in others.
  • Hidden: Everything (when opened directly), Search, Ask Capy, linked-item search, and suggestions.
  • Redacted: Linked items, product themes, timeboxes ("Private"), and flag lists ("[Private team story]").
  • Assigning a bug to a private team you don't belong to loses you access to it, so set the risk rating first.
• Cycle time resets on team change and reappears if the item returns to its original team (§7).
• Moving a story to another team clears its size. If that team uses backlog management, you need to be one of its backlog owners to assign stories to it.
• Switching methodology destroys data. Switching to Kanban permanently deletes all sprints. Switching to Scrum moves in-progress items to To do and marks them Unscheduled.
• Scrum scheduling moves items to To do. Dragging an item into any sprint or into Unscheduled moves it to To do, and Won't do items don't appear on the Scrum backlog at all.
• Deleting a sprint doesn't delete its items. They move to the top of Unscheduled, keeping their order.
• You can't reorder or move items while filters are applied. Estimated completion dates do stay visible under filters in Kanban views, so don't generalize from one behavior to the other.
• Releases are dated markers, not containers. Items relate to a release by date: estimated completion in Kanban, sprint end in Scrum. Rescheduling or deleting a release changes it everywhere it's used.
• An item is in at most one timebox. Adding it to another moves it.
• Unsized story points depend on context. The value used for an unsized story differs between totals, burndown, and throughput (§7).
• Throughput's current bar is a projection, not a count. Don't report it as delivered work.
• Two time zones are in play. Analytics and burndown use the team time zone. Everything's date filters use each viewer's browser time zone, so the same relative filter can return different items for different people.
• AI context tab names differ between the UI and MCP. The UI says Design decisions, Technical investigation, and Technical changes; MCP says DESIGN, INVESTIGATION, and SUMMARY. Bugs have no Design decisions tab.
• Story assistant changes are staged, not saved. Undo reaches only the most recent AI change. Show changes is a read-only way of viewing staged content, not a second accept step.
• Ask Capy and the Story assistant are different tools. Capy answers questions from completed, public work across the workspace and is read-only. The Story assistant authors a single story from its context and stages edits for review.
• Ask Capy is limited release. Its quota is shared by the whole workspace, not per user (§10).
• Tags allow one value per key. Applying a second value for the same key replaces the first.
• Restoring an item version can drop data. AC-level comments and attachments may be lost, while general comments and attachments below the text are kept. Atono warns first.
• Splitting stories:
  • Moving a parent AC with all its children keeps the original IDs.
  • Moving only some children copies the parent to the new story with a new ID.
  • Assignee, size, cycle time, general comments, and Slack channel don't carry over to the new story.
• Duplicating stories and bugs: Items in To do or In progress keep their workflow step, assignee, backlog, and timebox. Items in Done or Won't do lose those fields and go back to an intake lane. Comments and cycle time aren't copied.
• Deleting a team unassigns its unfinished items. Stories move to Story refinement. The docs don't say where unfinished bugs go.
• Users you can't delete:
  • The only admin of a team.
  • The only Owner of a flag.
  • The last user in the workspace.
  • Yourself.
• Deleting a user deletes their shared views. Any Home widgets built on those views stop showing content.
• Product Knowledge is two things, not one (§2).
• The intake lanes don't follow the workflow rules (§3).

14. Vocabulary quick reference

These are terms whose Atono meaning differs from the industry default, or that don't exist elsewhere.

Items and structure

• Backlog item — A story or bug. Epics and subtasks aren't backlog items.
• Handle / Item ID — The readable ID, such as STORY-123.
• Split story — Moves selected ACs into a new story (§13).
• Duplicate — Copies a story or bug (§13).
• Stakeholder — A team admin or backlog owner who isn't a member of the team.
• Everything — The workspace-wide item view, covering stories, bugs, and epics.
• View — A saved set of filters, sort, and columns. Views can be shared with users or teams and can back a Home widget.
• Follow — Starring an item so it appears in the Following widget and filter.
• External ID — The original Jira key or Linear ID, kept after import.

Product knowledge and AI

• Product knowledge — The Glossary (workspace level) plus AI context (item level).
• Concept — A single Glossary entry.
• AI context — Durable context on a story or bug. The tabs are Design decisions, Technical investigation, and Technical changes; the MCP names are DESIGN, INVESTIGATION, and SUMMARY.
• Design decisions — Recorded scope decisions and rationale on a story. The Story assistant writes them.
• Story assistant — Conversational AI that authors a single story and stages its changes.
• Create with AI — The Create new menu entry that starts a story from a description.
• Show changes — The Story assistant's read-only redline of staged edits.
• Story review — Announced, not shipped (§5).
• Capy / Ask Capy — The capybara mascot, and the AI assistant that answers questions from completed public work.
• Sparkle (✦) — Marks an AI-suggested value, or an action by the MCP server or Story assistant.
• Source — The Activities filter showing where a change came from: User, Integration (GitHub, Jira import, Linear import), API, MCP server, or Story assistant.

Estimation and metrics

• Persona — The reusable "As a [persona]" user type.
• Size / Story points — T-shirt size mapped to Fibonacci points (§7).
• Size it for me / Rate it for me — AI suggestions for story size and bug risk (§5).
• Risk rating — Probability × Impact, from 1 to 25, for bugs only.
• Cycle time window — The history used for team averages (§7).
• Outlier — An item excluded from cycle time math.
• Staleness indicator — An hourglass marking a statistically stalled item.
• Scope line — The burndown line showing total sprint points each day.
• Story throughput — Stories or points completed per period (§7).
• Served value duration — How long a flag has returned the same value in an environment.

Planning

• Story refinement / Bug triage — The two fixed intake lanes (§4.6).
• More info required — The Bug triage section that assigns a bug back to its reporter.
• Unscheduled — The part of a Scrum backlog holding items not in any sprint.
• Backlog management — The team setting that restricts story and sprint management to backlog owners.
• Product theme — Strategic grouping for stories only. Linear projects map here.
• Timebox — A dated group of stories and bugs shown on timelines. It's distinct from a sprint.
• Release — A workspace-global dated marker shown on timelines and team backlogs.
• Tag — A key:value label on stories, bugs, or epics.

Flags and usage

• Slice — A Customer and/or Location condition set that overrides a flag's environment default.
• Environment key — Connects code and the Chrome extension to a workspace environment.
• Mapped action — A click recorded by the Chrome extension and tied to a story.
• Feature engagement / Engagement — Usage shown on a story, and the workspace's top-features page.

---

Jira — Product Map (September 18, 2026)

A semantic model of Atlassian Jira (Jira Cloud) for AI agents. Built from a structured crawl of Atlassian's official support and developer documentation (support.atlassian.com, developer.atlassian.com, admin.atlassian.com) plus the official atlassian/atlassian-mcp-server repo, current to mid-September 2026. This is not a link index — it explains what Jira is, how its concepts relate, and the rules that govern them, so an agent can reason about Jira without re-reading the docs.

Scope note: this describes Jira Cloud (the SaaS product). Jira Data Center/Server behaves differently in several places (notably attachment limits and admin model) and is called out where it matters. "Jira Software," "Jira Work Management," and "Jira Service Management" are converging into one Jira; this map covers the software/agile core.

Terminology currency: Atlassian is mid-rollout of an "issue" → "work item" rename (UI-level, main push March 2025). This map treats work item = issue as exact synonyms and uses "issue" for anything API/JQL-facing, because the APIs and query language were not renamed.

---

1. What Jira is, in one paragraph

Jira is a highly configurable work-tracking platform built around a single primitive — the issue (now also called a "work item") — that moves through a customizable workflow of statuses, lives in exactly one project, and is grouped, filtered, and reported on through an extensive scheme system. Its defining trait is configurability: nearly everything (issue types, fields, screens, workflows, permissions, notifications) is expressed as a reusable scheme that admins compose and share across projects. Agile delivery (Scrum/Kanban boards, sprints, backlogs, velocity) sits on top of this generic issue engine as a board layer — a board is a saved filter with columns, not a container. The result is a system that can model almost any process, at the cost of significant administrative surface area. Jira's own current direction is AI: the Rovo layer (search, chat, agents) and an official remote MCP server now expose that issue graph to agents. Through 2026 that direction sharpened in two ways an agent should register. First, Rovo stopped being features bolted onto Jira and became the substrate: the Teamwork Graph now ingests code across repositories (Code Context, beta August 2026), and Jira Planner (Early Access, September 2026) plans from it — but publishes plans as Confluence Live Docs, so the planning artifact lives outside Jira. Second, the MCP server moved to a v2 discover/execute model (§6), which changes how an agent consumes Jira entirely.

Why this framing matters

Jira is the configuration-maximalist end of the work-tracking spectrum. The mental model that trips up both humans and agents is that Jira separates what an issue is (project + issue type + fields) from where it's shown (boards, filters, dashboards) from how it's governed (schemes and permissions). Those three planes are independent, and most "why can't I see / do / report on X" confusion comes from a mismatch between them — a status that isn't column-mapped, a field hidden by a field configuration, a permission scheme that doesn't grant browse, a board filter that excludes the issue. An agent that holds all three planes in mind at once will predict Jira's behavior; one that thinks only in "issues and statuses" will not.

---

2. The mental model — how the pieces relate

SITE  ({your-domain}.atlassian.net — an Atlassian org may hold several products)
│
├── PROJECT  (hard container; an issue lives in exactly 1; key prefix = PROJ)
│   │   Two project TYPES, a fork that changes almost everything:
│   │   ├── Team-managed  (was "next-gen") — self-contained, project admin configures, NO schemes
│   │   └── Company-managed (was "classic") — Jira admin configures via SHARED SCHEMES
│   │
│   ├── ISSUE / WORK ITEM ◄──────────── the primitive
│   │   ├── Issue type (Story / Task / Bug / Epic / Subtask / custom)
│   │   ├── Status ──── belongs to exactly one of 3 STATUS CATEGORIES (To Do/In Progress/Done)
│   │   ├── Resolution ──── separate field; "resolved" == this field is SET, not the status (see §12)
│   │   ├── Fields (system + custom; visibility governed by Field Configuration)
│   │   ├── Parent ──── unified hierarchy link (replaced legacy "Epic Link")
│   │   ├── Estimate ──── Story points (free numeric) / time / issue count
│   │   ├── Fix Version(s) / Affects Version(s) ──── release markers (project-scoped)
│   │   ├── Component(s) ──── project sub-category, optional default assignee
│   │   ├── Label(s) ──── the ONLY global, uncontrolled, cross-project tag
│   │   ├── Sprint ──── system field; can hold a HISTORY of sprints
│   │   ├── Rank (LexoRank) ──── global execution ordering, distinct from Priority
│   │   ├── Flagged ──── system flag; only value is "Impediment" (visual blocked marker)
│   │   ├── Development panel ──── linked branches/commits/PRs/builds/deploys + external FLAGS
│   │   ├── Comments, Attachments, Links (blocks/relates/duplicates — lateral, not hierarchy)
│   │   └── History / activity
│   │
│   ├── HIERARCHY (default levels)
│   │   Level 2+  Initiative / Feature / custom  ── Premium only, via PLANS
│   │   Level 1   Epic                            ── top of the STANDARD hierarchy (fixed position)
│   │   Level 0   Story · Task · Bug              ── the base "standard" work items (same level)
│   │   Level −1  Subtask                         ── child of a level-0 item only
│   │
│   ├── CONFIGURATION SCHEMES (company-managed only — the shared, admin-owned layer)
│   │   Workflow scheme · Issue type scheme · Screen scheme · Issue-type screen scheme
│   │   Field configuration scheme · Permission scheme · Notification scheme · Security scheme
│   │
│   └── VERSIONS · COMPONENTS  (project-scoped; do not span projects)
│
├── BOARD  (a filtered, columnized VIEW over a JQL filter — NOT a container)
│   ├── Scrum board ── Backlog + Sprints (time-boxed)
│   └── Kanban board ── continuous flow, WIP limits, optional Kanban backlog
│       └── Columns map to statuses · rightmost column defines "done" for sprint completion
│
├── PLANS  (Premium/Enterprise — "Advanced Roadmaps") ── cross-project program planning,
│          initiatives/custom levels, dependencies, capacity, scenario sandbox
│
├── JQL  (Jira Query Language) ── the query layer under filters, boards, dashboards, automation
│
├── AUTOMATION  (Trigger → Conditions → Actions; monthly execution caps by plan)
│
├── ROVO  (AI layer) ── Rovo Search · Rovo Chat · Rovo Agents · Rovo Dev
│
└── PERMISSIONS
   ├── Global permissions (site-wide, group-assigned)
   ├── Project permissions ── via permission SCHEME (company-managed) or in-project roles (team-managed)
   └── Org/Site admin (admin.atlassian.com)

The single most important structural fact: a board is not a container — it is a saved filter with columns. An issue lives in a project; it appears on a board only if it matches the board's JQL filter, its status is mapped to a column, and (for Scrum) its Sprint field is set. Break any of those three and the issue vanishes from the board while still existing in the project. Nearly every Jira surprise is a version of this.

---

3. The three status categories (universal spine)

Every status a team defines rolls up to exactly one of three fixed status categories. The categories and their colors are hard-coded; the statuses within them are fully customizable.

Rules an agent should know:

• Categories are fixed (three, non-customizable, fixed colors). Status names are free; many statuses can share one category.
• Two different "done" definitions coexist and can disagree — this is the single most important Jira subtlety:
  • Agile reports (velocity, burndown, sprint completion, CFD) treat an item as done when its status is in the rightmost board column.
  • Issue-navigator / Created-vs-Resolved treat an item as resolved when the Resolution field is set (see §12).
  • A status change alone does neither reliably unless configured to.
• A workflow may have conditions (who may transition), validators (input must be valid or the transition is blocked), and post-functions (run automatically after a successful transition — e.g. set Resolution).
• Company-managed workflows are governed by workflow schemes (shared, admin-owned, mapped per issue type). Team-managed projects edit their workflow directly in-project, with no scheme.

---

4. The distinctive concepts (what makes Jira not Linear)

If an agent internalizes one section, it should be this one. These are the parts a generic work-tracker model gets wrong.

4.1 Team-managed vs company-managed is a fork, not a setting

The single biggest branch in Jira's model. The same conceptual action has a different path, owner, and permission depending on project type:

There is no in-place conversion: you create a new project of the target type and bulk-move issues, remapping config. An agent must know which type a project is before reasoning about how to change its workflow or who can.

The fork started to blur in August 2026 (beta). Global — site-wide — statuses can now be added to team-managed workflows, so a status can be shared across team-managed spaces instead of being invented per project. It is opt-in via Jira Labs and Atlassian says it will become the default; the workflow create and update APIs accept global statuses, space templates build workflows with them when the beta is on, and API shapes are unchanged. Two consequences: "team-managed projects share no configuration" is no longer reliably true, and two team-managed projects showing the same status name may now be the same status rather than two coincidental ones. Check whether the beta is enabled before assuming either.

4.2 Schemes — configuration as shared, reusable objects

In company-managed projects, almost every aspect of an issue's behavior is a scheme (workflow, issue type, screen, field configuration, permission, notification, security). A scheme is defined once and attached to many projects, so an admin change propagates org-wide. This is the source of both Jira's power (org-wide standardization) and its opacity (a field's behavior is set three layers away, in a field-configuration scheme, not on the issue). Team-managed projects deliberately have no schemes.

4.3 Resolution is a separate field from status

Jira splits where an issue is (Status) from why it closed (Resolution). An issue is "resolved" only when the Resolution field has a value — a Done-status issue with an empty Resolution shows as Unresolved and is excluded from resolved-work reports. Correct setups set Resolution via a transition post-function and clear it on reopen. This is Jira's #1 misconfiguration and #1 agent gotcha (see §12).

4.4 Boards are views, not containers (and the caps are in retreat)

A Scrum or Kanban board is a JQL filter + column mapping. Columns map to statuses; the rightmost column defines sprint-completion "done." An issue's presence on a board is derived, not stored. Boards can span projects (company-managed only). This inverts the intuition that "the board" owns the work — the project does.

The board engine changed in 2026; the model did not. Team-managed boards (GA in the Summer Release, by end of August 2026) load about 22% faster and gained swimlanes, subtasks on cards, inline editing, saved views — and no more work-item caps. Company-managed boards began moving to the same modern engine from September 2026, with the EAP closing the week of 7 September: independent column scrolling and loading, fixed or flexible column widths, quick filters renamed "custom filters", and saved favorite filter-and-view combinations. The practical effect is that the 5,000-item display ceiling on boards, backlogs, and timelines stops being a hard wall — a large board loads and keeps working rather than failing to render. Treat the 5,000 figure in §10 as a limit in retreat, and check which engine a board is on before quoting it.

4.5 The issue hierarchy is fixed at the standard levels

Epic (level 1) sits atop Story/Task/Bug (level 0), which sit atop Subtask (level −1). This shape is fixed — you can rename Epic but not reposition it, and subtasks attach only to level-0 items (recent change: subtasks can no longer be created directly under an Epic). Levels above Epic (Initiative, Feature, custom) exist only in Plans on Premium/Enterprise. The modern unified parent link is the Parent field; the legacy "Epic Link" custom field has been merged into it.

4.6 Feature flags are a visibility surface, not a native capability

Jira has no native feature-flag engine. The Development/Releases panel displays flags from external tools (LaunchDarkly, Split) — name, environment, on/off, rollout %. Flags link to issues by referencing the issue key. Jira never evaluates or toggles a flag; that logic lives entirely in the external tool. Jira is a read/visibility surface only.

4.7 Automation is native but metered

"Automation for Jira" is a no-code rule engine (Trigger → Conditions → Actions) with smart-value templating. It's genuinely powerful (scheduled rules, webhooks, dev-event triggers, for-each branches) but execution is capped monthly by plan (see §5/§10), and since Nov 2023 single-project and multi-project runs both count. Hit the cap and all rules for that product stop until the month resets.

---

5. AI features (Rovo) and their gating

Atlassian consolidated its AI under the Rovo brand (formerly "Atlassian Intelligence"). Three pillars: Rovo Search, Rovo Chat, Rovo Agents, plus Rovo Dev (developer agent + CLI) and Rovo Studio (no-code agent builder).

Gating rules an agent should know:

• Rovo is auto-enabled on Standard, Premium, and Enterprise — not Free. Not available in Government Cloud or Confluence sandboxes. Admin-toggleable via Atlassian Administration → Rovo.
• Metered by Rovo credits per user/month: 25 (Standard) / 70 (Premium) / 150 (Enterprise); "Teamwork Collection" allowances are far larger. As of mid-2026 Atlassian was not billing overage and commits to 90 days' notice before charging.
• Jira Planner needs Confluence, because the plan it produces is a Confluence Live Doc, not a Jira object. A Jira-only site cannot use it. This is the clearest case of Atlassian's AI layer treating the suite, not Jira, as the unit — an agent asked to "make a plan in Jira" should know the artifact lands elsewhere.
• Capacity planning (Summer Release, GA) is Premium/Enterprise only, and does not populate itself from existing assignees — allocation is entered by hand.

---

6. The MCP server & API — how agents actually use Jira

Atlassian Remote MCP Server (official)

A cloud-hosted, remote MCP server (github.com/atlassian/atlassian-mcp-server) — beta May 2025 (Claude was the first official partner), GA February 2026. Marketed as Rovo MCP.

• Covers: Jira, Confluence, Jira Service Management, Bitbucket Cloud, Compass.
• Endpoint: https://mcp.atlassian.com/v2/mcp — the recommended endpoint for all new setups. (Verified against the atlassian/atlassian-mcp-server README, 18 September 2026.) The v1 endpoints (https://mcp.atlassian.com/v1/mcp/authv2 and https://mcp.atlassian.com/v1/mcp) remain functional, and existing v1 connections automatically gain v2 tool access — so there is no reason to add a v2 connection beside a working v1 one, and doing so is the trap in §12. The legacy Server-Sent Events endpoint https://mcp.atlassian.com/v1/sse was withdrawn after 30 June 2026 and is already dead; that is the only announced sunset.
• The v2 tool model is Primary-plus-discovery, not a flat list. Tools marked Primary are visible to agents directly; the rest are discovered on demand, which preserves client context and lets new tools appear without reconnecting. Atlassian reports the pattern cuts up-front context consumption by over 50%, and tool responses were trimmed too. The consequence for an agent: "how many tools does Jira MCP have" is the wrong question — v1's flat ~72+ list is not the shape any more. If a gateway genuinely needs the whole surface up front, append ?tools=all to the endpoint for a paginated flat list. That is the supported escape hatch, and the only correct way to enumerate.
• Scopes: permission groups per product — for example read_jira, write_confluence, search_atlassian — which admins grant or revoke at group level. All actions respect existing project- or space-level roles. Note these are permission groups, not tool names; v1's cross-product tools read_teamwork_graph and search_atlassian were tools, and the collision of spelling is a trap. (Unverified against the README: the v2 preview announcement stated that v2 uses a new DCR OAuth endpoint and that its OAuth scopes are MCP-specific and not reusable for general REST calls, with service-account-token scope still in development. Treat as reported, not confirmed.)
• Auth: OAuth 2.1 (browser, for Jira/Confluence/Compass) or API tokens (headless; mandatory for JSM and Bitbucket). It is a proxy that respects the signed-in user's existing permissions and does not store or cache data.
• Constraints: TLS 1.2+, honors org IP allowlists. Admins can manage domain access for the Rovo MCP server — using Atlassian's list of supported domains, blocking it, or allowing individually selected domains. No published rate limits; docs recommend maxResults: 10 on searches to control token usage.
• Naming: (reported, not confirmed against the README) v2 standardized several tool names, including searchAtlassian and fetchAtlassian — camelCase, as against v1's snake_case. If true, older prompts and configs naming v1 tools will not resolve. Verify before relying on a specific tool name.

REST API

• Base: https://{domain}.atlassian.net/rest/api/3/{resource} (direct) or https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/{resource} (OAuth 3LO). v3 is current (rich text as Atlassian Document Format / ADF).
• Auth: API token (Basic = email + token), OAuth 2.0 (3LO), or Forge/Connect app auth. Keys act as the user; actions attribute to that user.
• Cost-based ("points") rate limiting (governs OAuth 3LO + Forge from March 2, 2026; API-token traffic stays on older burst limits): each request costs points by work done (base 1/request; reads add per-object cost; writes = 1). Default shared global pool ~65,000 points/hour; opt-in per-tenant pools scale with plan and users, capped at 500,000 points/hour. Three concurrent limits: hourly points, per-second burst, and per-issue write limits (20 ops/2s, 100 ops/30s). Breach → 429, respect Retry-After, back off with jitter.
• Pagination: JQL search moved to token-based pagination — POST /rest/api/3/search/jql returns a nextPageToken; offset pagination (startAt/total) is deprecated for search.
• Extensibility: Forge (serverless, Atlassian-hosted) and Connect (older iframe/webhook) apps extend Jira on the same rate regime.

JQL — the query layer

Field → operator → value(s)/function. Operators include =, ~ (contains), IN, IS EMPTY, and the history operators WAS / CHANGED (query past states). Functions: currentUser(), membersOf(), openSprints(), linkedIssues(), startOfDay(). ORDER BY must be last. Critically: raw JQL searches ALL issues regardless of status — including Done/Closed/resolved — unless you filter them out. (Board views may hide old done items; JQL does not.)

---

7. Metrics — exact definitions

Agents get these wrong by assuming industry-standard definitions. Jira's are specific, and several depend on configuration rather than being fixed.

• Velocity — average of total completed estimates over recent sprints; two bars per sprint (Commitment vs Completed). "Completed" = status in the rightmost board column (not the Resolution field). Subtask estimates are excluded — only parent-level estimates count.
• Sprint burndown — remaining work vs time within one sprint; grey Guideline = ideal line. Adding items/subtasks mid-sprint is scope change. Board-specific (only the board's filtered, column-mapped items).
• Burnup — completed vs total scope as two lines, so scope changes are legible (unlike burndown).
• Sprint report — buckets a completed sprint's issues into Completed / Incomplete (carryover) / Removed, with a timestamped scope-change event log — the only native place to trace when scope changed.
• Control chart (cycle time / lead time) — cycle time = time spent working on an item (from work begins to work complete); lead time = from when the item was logged (created) to complete, including queue time. Which statuses count is user-configured, not fixed — practically cycle = In Progress-category → Done-category; lead = creation → Done. Uses a rolling average (window = 20% of shown items, odd, min 5) with a std-dev band.
• Cumulative flow diagram (CFD) — stacked area of item counts per status/column over time; a widening band = a bottleneck in that column.
• Created vs Resolved — created vs resolved over time; red = backlog growing, green = shrinking. "Resolved" here keys off the Resolution field (see §12).
• Epic report / burndown — progress toward an epic; forecasts sprints needed from historical velocity.
• Version report / Release burndown — projected release date for a version, flagging if it will slip.

Two aging notes: Jira has no native "time in status" report (Marketplace-app territory); the board's Days in Column dots are the closest native aging signal. Flagging an issue sets the system Flagged = Impediment field, turns the card yellow, and is a visual blocked marker — it does not change status (flagged is not EMPTY in JQL).

---

8. Roles and permissions

Jira permissions operate on multiple independent planes; the plane depends on project type.

Site/Org level (admin.atlassian.com):

• Org admin / Site admin — manage the Atlassian org, product access grants, and product-admin rights.
• Global permissions — site-wide capabilities (Administer Jira, Browse users, Bulk change, Create shared objects); assigned to groups; editable only by admins.

Company-managed project permissions (scheme-driven):

• Permission scheme — a reusable map of permissions (Browse Projects, Create/Assign/Transition Issues, Administer Projects…) to holders = users, groups, or project roles. Shared across projects; changes require a Jira admin.
• Project roles — like groups but scoped to one project (Administrator, Member, custom). Role definitions are global; membership is per-project and editable by project admins (unlike group membership, which needs a site admin). Best practice: schemes hold roles; groups carry identity.

Team-managed project permissions:

• Project admins manage access directly via custom roles created in-project — flexible and autonomous, but no shared schemes (risk of "role sprawl").

The recurring surprise: because company-managed permissions live in a shared scheme three layers from the issue, "why can't user X do Y" is usually a permission-scheme holder mismatch, not an issue-level setting.

---

9. Feature flags — the external integration model

Jira does not manage flags; it surfaces them. Detail worth holding:

• The Development/Releases panel on an issue shows linked flags from LaunchDarkly / Split: flag name, environment, enabled/disabled, rollout %. Selecting one opens a dev dialog.
• Flags link to issues by referencing the issue key (e.g. LaunchDarkly auto-adds a Jira link when connected). "+ Add feature flag" can create/link from the panel.
• Automation smart values include a development/feature-flag category, but Jira never evaluates or toggles a flag — the engine is entirely external. Treat Jira as read-only visibility over someone else's flag system.

(Contrast for positioning: this is the inverse of platforms where the flag lives inside the work item and is toggled from it — in Jira the flag lives in a separate product and Jira merely mirrors its state.)

---

10. Hard limits and constants (quick reference)

Many current caps come from Atlassian's data limits & guardrails page with phased enforcement (dates noted). Some are recommendations, not hard walls.

Not published as fixed caps: max subtasks per issue, max comments per issue, boards per project, sprints per board (governed by the guardrails, not per-issue numbers).

Board display caps are being lifted (2026). The long-standing 5,000-item ceiling on what a board, backlog, or timeline could show is gone on team-managed boards (GA, August 2026) and is going on company-managed boards with the modern engine (rolling out from September 2026). It was a display limit, not a storage one, and the modern engine replaces failure-to-render with incremental loading. Do not quote 5,000 as a current hard limit without checking the board's engine.

Issue key scheme: PROJ-123 (project key = 2+ uppercase letters + per-project sequential counter). Keys are never reused. Moving an issue between projects gives it a new key; the old key becomes a redirecting alias. Moving back assigns yet another new number (the original is not reclaimed). Text matching the key pattern auto-hyperlinks in descriptions, comments, and commit messages.

---

11. Integrations

• Confluence — the native knowledge base. Issues surface related Confluence content (permission-respecting); pages embed Jira issues/JQL/roadmaps. Rovo searches across both.
• Bitbucket / GitHub / GitLab — the Development panel shows linked branches, commits, PRs, builds, deployments. Smart commits and PR/branch linking work by putting the issue key in branch names, commit messages, and PR titles; smart-commit syntax can comment, log time, and transition issues from a commit.
• Slack / Teams — two-way notifications and issue creation from chat (Rovo can generate issues from context). Microsoft Teams natural-language integration went GA in August 2026: a Teams conversation converts into Jira actions by description, without switching tools.
• Loom — transcripts are parsed for decisions and action items and mapped onto work items (GA, Summer Release 2026).
• Atlassian Projects — work items link up to Projects for rolled-up initiative tracking (GA, Summer Release 2026). Note the collision: this is a distinct Atlassian object, not a Jira project, and not the same thing as a Plan.
• Marketplace — thousands of Connect/Forge apps (Tempo, ScriptRunner, Xray, structure tools) extend Jira; many "native-feeling" capabilities (time-in-status, test management) are actually apps.
• Imports — CSV, plus migration tooling from other trackers. External IDs are commonly retained for cross-reference.

---

12. Gotchas an agent will otherwise get wrong

• Resolution vs Status is the #1 trap. An issue in a Done status with an empty Resolution is "Unresolved" and missing from resolved-work reports. Set Resolution via a transition post-function; clear it on reopen (reopening does not auto-clear it). Never expose Resolution on the create/edit screen — drive it only through transitions.
• Two "done" definitions disagree. Agile reports key off the rightmost board column; Created-vs-Resolved and "Unresolved" key off the Resolution field. The same issue can be "done" to one and not the other.
• A board is a filter, not a container. An issue can match the board's JQL yet be missing because its status isn't column-mapped or its Sprint field is unset/hidden. Sprints only appear on a board if the board filter matches ≥1 issue in the sprint.
• Team-managed and company-managed can't share hierarchy or schemes. An item in one type can't be parented to the other; migrating between types is a move-and-remap, not a toggle, and loses/remaps config.
• Moving issues remaps or strips fields. Fields absent in the target project lose their values; subtasks must move with their parent; issue types may need remapping. The key changes (§10).
• Sprint completion uses the rightmost column, not the Done category or Resolution. Subtasks not in the rightmost column make the parent incomplete.
• The story-points field is not one field. Company-managed uses "Story Points"; team-managed uses "Story point estimate" — cross-project reports that expect one silently miss the other.
• Automation caps are shared and hard. Hit the monthly cap and every rule for that product stops until reset (since Nov 2023, multi-project/global runs count; single-project runs are exempt from the usage cap but still subject to service limits).
• JQL searches everything, including done/closed work — the opposite default of most board views. Filter status/resolution explicitly.
• Delete is permanent; archive (Premium/Enterprise) is reversible. Deleting a project deletes its issues.
• Field Configuration can silently break behavior. A hidden required field (e.g. Sprint) can make an issue un-savable or invisible to a board without any obvious error.
• Rank ≠ Priority. Rank (LexoRank) is execution order and is rewritten on every reorder (Jira rebalances ranks in the background); Priority is a business-value field. Reordering a backlog changes Rank, not Priority.
• "next-gen"/"classic" are the old names for team-managed/company-managed — older docs and UI use them interchangeably.
• Search runs on an index. Very recent edits or reindex windows can make JQL results briefly disagree with the actual data.
• Don't connect v1 and v2 at the same time. An existing v1 connection already gets v2's tools automatically, so adding v2 beside it buys nothing and risks two endpoints declaring overlapping tools. Point new setups at v2/mcp and leave working v1 connections alone. Only the legacy /v1/sse endpoint is actually gone (after 30 June 2026).
• Don't count Jira's MCP tools. Under v2 only Primary tools are visible at connect time and the rest are discovered at runtime, so any fixed number — including the ~72+ that described v1 — is wrong by construction. If you must enumerate, ?tools=all returns a paginated flat list.
• MCP scopes may not be API scopes. The v2 announcement says its OAuth scopes are MCP-specific and not reusable for general REST calls, so a token that works for MCP may fail against /rest/api/3. Not restated in the repo README — verify before depending on it.
• "Team-managed shares no config" is now conditional. With the August 2026 global-statuses beta enabled, team-managed workflows can use site-wide statuses (§4.1). Check the Labs setting before asserting isolation.
• Jira Planner's output is a Confluence page. It is Early Access, needs Rovo plus Teamwork Graph plus Confluence, and publishes plans as Live Docs. A plan made there is not a Jira object and won't be found by JQL.
• Capacity planning is Premium/Enterprise and is filled in by hand. It does not derive allocation from existing assignees.

---

13. Vocabulary quick reference

Terms whose Jira meaning differs from generic agile, or that are Jira-specific:

• Work item — the current name for Issue (UI rename, ~March 2025); identical object. APIs/JQL still say "issue."
• Resolution — a separate field recording why an issue closed; presence of a value = "resolved." Not a status.
• Status Category — the three fixed buckets (To Do / In Progress / Done) behind every status; drives reporting and coloring.
• Fix Version vs Affects Version — release the work ships in vs version a bug appears in.
• Component — a project sub-category; can carry a default assignee.
• Parent — the unified hierarchy link; Epic Link is the deprecated legacy field merged into it.
• Board vs Project — a Board is a filtered, columnized view (can span projects); a Project is the hard container.
• Filter — a saved JQL query underlying boards, dashboards, subscriptions.
• Quickfilter — a board toggle applying extra JQL atop the board filter.
• Swimlane — a horizontal board grouping (by assignee, epic, query…).
• Scheme (Workflow / Permission / Notification / Screen / Field Configuration / Issue Type) — a reusable config object shared across company-managed projects; the core of Jira's configurability.
• Screen — the set/arrangement of fields shown for create/edit/view or a specific transition.
• Field Configuration — governs field behavior (required, hidden, description).
• Story Points / Story point estimate — the numeric estimation field; named differently in company- vs team-managed projects.
• Sprint — a time-boxed iteration; a system field that can hold a history of sprints an issue was in.
• Backlog — ordered issues not in an active sprint (or the Kanban backlog view).
• Rank / LexoRank — the global execution-ordering string; rewritten on reorder; distinct from Priority.
• JQL — Jira Query Language; the query layer under everything.
• Team-managed (was "next-gen") vs Company-managed (was "classic") — the project-type fork (§4.1).
• Plans — cross-project/portfolio planning (Premium/Enterprise); lineage: Portfolio for Jira → Advanced Roadmaps → Plans.
• Rovo — Atlassian's AI layer: Rovo Search, Rovo Chat, Rovo Agents, Rovo Dev, Rovo Studio.
• Rovo credits — the per-user monthly consumption unit metering AI usage.
• Flagged / Impediment — the system flag marking an issue as blocked (visual only; the only value is "Impediment").
• Development panel — the issue panel showing linked dev activity and external feature flags.
• Forge / Connect — Atlassian's app-extensibility platforms (serverless / iframe-webhook).
• Rovo MCP v2 — the current MCP server (https://mcp.atlassian.com/v2/mcp), using a discover/execute tool model instead of a flat tool list; v1 still runs alongside it.
• Discover/execute — the v2 pattern: a small set of common tools is exposed at connect time and the rest are discovered on demand, cutting up-front context by over half.
• Teamwork Graph — Atlassian's cross-product knowledge graph; since August 2026 it ingests multi-repo code via Code Context (beta).
• Jira Planner — Early Access (September 2026) AI planning that reads code and Teamwork Graph context and publishes an editable plan as a Confluence Live Doc, linked back to Jira.
• Live Doc — the Confluence artifact Jira Planner writes to; co-editable and commentable, and not a Jira object.
• Delivery Agent — the built-in Rovo agent covering recurring coordination: health checks, standup digests.
• Formula field — an auto-calculated field; Rovo can write the formula from a plain-language description.
• Global status (team-managed) — a site-wide status usable in a team-managed workflow; opt-in beta from August 2026, slated to become default.
• Custom filter — the modern company-managed board's name for what was a quick filter.
• Atlassian Projects — a separate Atlassian object work items roll up into for initiative tracking; not a Jira project.

---

Linear — Product Map (September 18, 2026)

A semantic model of Linear (linear.app) for AI agents. Built from a structured crawl of Linear's official documentation, developer docs, changelog, and "The Linear Method" (linear.app/docs, developers.linear.app, linear.app/changelog, linear.app/method), current to mid-September 2026. This is not a link index — it explains what Linear is, how its concepts relate, and the rules that govern them, so an agent can reason about Linear without re-reading the docs.

---

1. What Linear is, in one paragraph

Linear is an opinionated, low-configuration work-tracking tool built for software product teams, organized around a fast, keyboard-first issue tracker with a deliberately small set of well-chosen primitives. Its unit is the issue, which belongs to exactly one team, moves through that team's workflow of statuses, and is planned along two parallel axes: a time axis (Cycles — Linear's word for sprints) and an outcome axis (Projects → Milestones, grouped upward into Initiatives). Where Jira maximizes configurability, Linear maximizes speed and defaults — it does fewer things and does them the same way for everyone, encoded as "The Linear Method." Three things define its current direction: it treats AI agents as first-class actors (agents can be assigned, @-mentioned, and delegated issues, with a full Agent Interaction SDK and session lifecycle); it pushes AI into intake (Triage Intelligence auto-routes, labels, and de-duplicates incoming work); and through 2026 it pushed past planning into execution and deployment — Releases (April 2026) tracks what is actually live, Loops (July 2026) run recurring agent workflows on a schedule or a trigger, and coding sessions (August 2026) give the agent an environment and a browser to test in.

Why this framing matters

Linear's design thesis is the inverse of Jira's: fewer knobs, stronger opinions. There is no per-issue-type custom workflow, no scheme system, no "sprint" as a separately named object. This makes Linear predictable — an agent can assume the defaults hold, because Linear intentionally does not let teams reshape the model as freely. The mental-model forks an agent must hold are (1) Cycle vs Project — time-boxed team rhythm vs cross-team outcome — an issue can be in both; (2) state type vs state name — teams invent status names, but behavior is driven by which of five fixed types the status maps to; and (3) planning vs deployment — a Release is not a third planning container but a record of what shipped, fed by CI/CD rather than by a person (§4.1).

One caution about the "low-configuration" framing: it still holds for the tracker, but Linear's agent surface is now the configurable part. Loops, coding-session environments, spend limits, and app approvals are all things a workspace sets up and can get wrong. An agent reasoning about Linear should not assume defaults hold there the way they do for issues and statuses.

---

2. The mental model — how the pieces relate

WORKSPACE  (linear.app/{name} — one company; holds all teams, projects, initiatives)
│
├── TEAM  (primary org unit; owns its OWN workflow, cycles, triage, labels)
│   │   Can nest: SUB-TEAMS up to 5 levels; sub-teams inherit workflow/cycles/labels
│   │
│   ├── ISSUE ◄──────────────── the unit of work (belongs to EXACTLY ONE team)
│   │   ├── Identifier  TEAM-123  (team key + per-team sequential number)
│   │   ├── Status ──── maps to one of 5 STATE TYPES (+ Triage, Duplicate) — see §3
│   │   ├── Priority ── fixed 5-value enum (No/Urgent/High/Medium/Low) — see §4.4
│   │   ├── Estimate ── Exponential / Fibonacci / Linear / T-shirt (team-chosen)
│   │   ├── Assignee (+ can be DELEGATED to an AI agent; human stays owner)
│   │   ├── Label(s) ── workspace- or team-level; label groups = single-select
│   │   ├── Project (≤1) · Project Milestone · Cycle (≤1, of its team)
│   │   ├── Sub-issues ── may live in a DIFFERENT project/team than the parent
│   │   ├── Relations ── Blocking / Blocked by / Related / Duplicate
│   │   ├── SLA (Business+) · Customer Requests · Comments · Documents · Attachments
│   │   └── Git branch name (issue ID embedded → auto-links PRs)
│   │
│   ├── WORKFLOW ──── the team's ordered set of issue statuses (each mapped to a type)
│   ├── CYCLE ──────── the team's repeating 1–8 week time-box (= sprint); auto-rollover
│   │   └── Cooldown ── optional buffer between cycles
│   └── TRIAGE ─────── the team's intake inbox (a special state type) — see §4.6
│
├── PROJECT  (outcome-scoped body of work; CAN SPAN MULTIPLE TEAMS)
│   ├── Lead · Members · Priority · Start/Target date · Status (Backlog/Planned/
│   │   In Progress/Completed/Canceled/Paused) · progress graph
│   ├── PROJECT MILESTONE ── ordered checkpoint inside one project (Alpha/Beta/GA)
│   └── PROJECT UPDATE ── periodic health: On track / At risk / Off track
│
├── INITIATIVE  (workspace-level; groups PROJECTS toward a strategic goal)
│   ├── Owner — a person, or (Aug 2026) a TEAM · Target date
│   │   Status (Proposed/Planned/Active/Completed/Canceled)
│   ├── SUB-INITIATIVES (nest; parent rolls up child projects)
│   └── INITIATIVE UPDATE ── rolls up contained project health
│   └── (was called "Roadmaps"; the roadmap TIMELINE is now a visualization/view)
│
├── RELEASE  (Apr 2026 — the DEPLOYMENT axis; NOT a planning container)
│   ├── fed by CI/CD: environments, versions, deploy status
│   ├── moves issue status when the code lands in production
│   └── release notes for one release or a RANGE (agent can draft them)
│       15 release pipelines on Business · unlimited on Enterprise
│
├── LOOP  (Jul 2026 — recurring agent workflow; Business+, burns AI credits)
│   ├── Trigger: a schedule, OR workspace activity (issue / project /
│   │   initiative / cycle changes)
│   └── Acts via Linear Agent: triage and research incoming issues, dispatch
│       to coding agents, edit documents, post updates to Slack
│
├── VIEWS  (saved, filtered lenses over issues/projects/initiatives; workspace or team)
│   └── My Issues · Inbox (Priority tab, Sep 2026) · Insights panel
│
├── INSIGHTS  (Business+) ── native real-time analytics (Measure × Slice × Segment)
│
├── AGENTS PLATFORM  ── agents as first-class actors (Agent Interaction SDK, sessions)
├── MCP SERVER  (mcp.linear.app) · GraphQL API (api.linear.app/graphql)
│
└── CUSTOMER REQUESTS / ASKS  ── feedback + Slack intake feeding Triage

The single most important structural fact: planning happens on two independent axes. A Cycle is time-boxed, team-scoped, and recurring (momentum). A Project is outcome-scoped, finite, and can span teams (delivery). An issue can belong to one Cycle and one Project at once — they answer "when" and "toward what," not the same question. Collapsing them is the most common modeling error.

---

3. The five state types (universal spine)

Every status a team defines maps to exactly one of five workflow state TYPES (Linear says "types," not "categories"), plus Triage as a special intake type and Duplicate as a system status.

Rules an agent should know:

• Teams create any number of named statuses, each assigned to one of the five types; at least one status must exist per type. Behavior follows the type, not the name.
• Progress/completion math counts issues in the Completed type; Canceled issues are excluded from totals (Completed and Canceled are both "closed" but semantically opposite).
• Cycle rollover carries only issues that are not Completed/Canceled (and not moved to Backlog/Triage) into the next cycle.
• Default status for new issues must be a Backlog- or Unstarted-type status.
• Duplicate is a system-managed status (Canceled type), applied automatically when merging duplicates; it can't be renamed.

---

4. The distinctive concepts (what makes Linear not Jira)

If an agent internalizes one section, it should be this one.

4.1 Cycle vs Project — the two planning axes (and Release, which is not one)

• Cycle — a team's repeating, time-boxed planning period; Linear's word for a sprint. Configurable 1–8 weeks, fixed start day, auto-repeating. Team-scoped. Optional Cooldown buffer after each. Autopilot rollover: unfinished issues automatically move to the next cycle at cycle end (you cannot keep unfinished work in a closed cycle). Velocity/capacity computed from the previous 3 completed cycles. Up to 15 future cycles can be pre-created.
• Project — an outcome-scoped, finite body of work with a target date, lead, and its own status; can span multiple teams. Subdivided by Project Milestones. Carries Project Updates with health (On track / At risk / Off track).
• Release (April 2026) — a third axis, and not a planning one. A Release records what has actually shipped: it is fed by CI/CD rather than by a person, tracks environments and versions, and moves an issue's status when its code lands in production — the distinction between merged and live. Release notes can be written for one release or a range, and Linear Agent can draft them from the included issues. 15 release pipelines on Business, unlimited on Enterprise.

An issue can be in one Cycle and one Project simultaneously, and separately appear in a Release. Cycles answer "when"; Projects answer "toward what"; Releases answer "is it live." Only the first two are planning containers.

4.2 Initiatives — the strategic layer above projects

Initiatives group multiple projects toward a company objective, can nest into sub-initiatives, and roll up project health via Initiative Updates. ("Roadmaps" was renamed to Initiatives; the roadmap timeline persists as a Gantt-style visualization of projects/initiatives.) Hierarchy: Initiative → Projects → Issues, running parallel to the team → cycle → issue execution axis.

4.3 Agents are first-class actors

Linear treats AI agents as workspace participants, not external callers — the clearest structural difference from most trackers:

• Agents can be @-mentioned, assigned, and delegated issues, and can create/reply to comments. Delegating an issue to an agent keeps the human teammate as primary owner (it still shows in their My Issues).
• An agent is a registered Application (OAuth app with webhooks). Auth uses OAuth2 with actor=app; scopes app:assignable / app:mentionable enable delegation/mentions. Admin scope is not available to app actors.
• Work runs as an AgentSession with a 6-state lifecycle (pending, active, error, awaitingInput, complete, stale) driven by 5 activity types emitted via agentActivityCreate: thought, action, response, elicitation, error. On a session created event the agent must emit an activity within 10 seconds or be marked unresponsive.
• Linear's own agent runs coding sessions (spec → code) and files issues from Intercom/Zendesk/Gong conversations into Triage. Building agents is free and they don't count as billable users.

Coding sessions got an environment and a browser (August 2026). The agent detects and installs the toolchains and dependencies a codebase needs (Python, Ruby, Go and more); teams can pin runtime versions, add setup scripts, and set environment variables. It then tests in a real browser — opens the app, walks a flow, verifies the implementation, captures before-and-after screenshots, and can fix and retest before handing back. Pricing is two-part and unusually explicit: model tokens at the provider's published rates with no markup, plus $0.25 per 20-minute block of sandbox runtime. Admins set workspace-wide and per-user spend limits resetting daily, weekly, or monthly; hitting one pauses AI credit usage until it resets or an admin raises it.

Drafting is agent-assisted too (September 2026). A project composer lets you develop an idea with Linear Agent — pulling context from the workspace and connected tools — before a live project exists. Drafts auto-save.

4.4 Priority is a fixed 5-value enum, not a magnitude

No priority (0) · Urgent (1) · High (2) · Medium (3) · Low (4). The number is an enum identity, not a severity magnitude — a filter for priority ≤ 2 returns Urgent + High. A team setting controls whether "No priority" sorts first or last. Setting Urgent notifies the assignee. Project priority (added July 2024) uses the same scale. There is no custom priority scale — this is a deliberate non-configuration.

4.5 Estimates are team-chosen scales that all resolve to numbers

Four scales, enabled per team: Exponential (1,2,4,8,16), Fibonacci (1,2,3,5,8), Linear (1,2,3,4,5), T-shirt (XS,S,M,L,XL); extended scales add two more values. T-shirt sizes map to Fibonacci numbers for analytics (XS=1…XXXL=21). Un-estimated issues default to 1 point (configurable); an explicit 0 estimate is optionally allowed and is distinct from "unestimated." Estimates drive cycle/project % completion and cycle capacity.

4.6 Triage — a dedicated intake state

Incoming work doesn't land in a generic backlog — it lands in a per-team Triage inbox (a special state type). Issues enter Triage from integrations (Slack, Sentry, Intercom/Zendesk/Front), Asks, agents, non-team members, and the API. Keyboard actions: Accept (1) → default status; Mark duplicate (2) → merge; Decline (3) → Canceled; Snooze (H). Triage rules can require fields (e.g. priority) before an issue leaves, auto-route team/labels, and auto-delegate to an agent. On-call rotation integrates with PagerDuty/Opsgenie/Rootly/incident.io.

4.7 Loops — recurring agent workflows (July 2026)

The piece with no equivalent in Jira or most trackers. A Loop is a standing instruction to Linear Agent that runs on a schedule or on workspace activity — an issue changing, a project or initiative status moving, a cycle being created (triggers widened September 2026).

What a Loop can do: review incoming issues, research root causes, dispatch work to coding agents, create follow-up work from unstructured input such as meeting transcripts, keep launch plans and project specs current, edit documents, and post updates to Slack.

Loops live at team and workspace level with shared visibility. Members with the right permissions can read a Loop's instructions, inspect its configuration, and audit each run; any run can be continued to review the work and add context.

Business and Enterprise only, and they consume AI credits per run. This is the first Linear feature where a misconfigured object costs money continuously, which is why the audit trail exists.

For an agent, the consequence is that workspace state may change with no human actor behind it. Attribution still names the Loop, so check the actor before assuming a person made a decision.

4.8 No native feature flags; native analytics is "Insights"

Linear has no native feature-flag capability (teams integrate external tools like LaunchDarkly). Its native analytics is Insights (Business+): real-time charts built as Measure × Slice × Segment over live issue data (see §7).

---

5. AI features and their gating

Gating rules an agent should know:

• Advanced AI intake (Triage Intelligence) tracks the Business/Enterprise tier alongside Insights, Asks, and SLAs. The AI page publishes no per-feature price table.
• The MCP server and the Agents platform are free to use and build against — agents don't count as billable users.

---

6. The MCP server & API — how agents actually use Linear

Linear MCP server (official, remote-hosted)

• Built with Cloudflare and Anthropic; remote-hosted.
• Endpoints: read-write https://mcp.linear.app/mcp (Streamable HTTP); read-only https://mcp.linear.app/mcp/readonly; deprecated legacy …/sse.
• Auth: OAuth 2.1 with dynamic client registration (interactive browser approval); also Bearer token, Linear API keys, and Enterprise SAML/Okta-managed auth.
• ~23–25+ tools for finding/creating/updating issues, projects, comments: listing (list_issues, list_projects, list_teams, list_cycles, list_comments, list_issue_labels, list_issue_statuses…), reading (get_issue, get_project, get_team, get_user…), writing (create_issue — also updates if id passed — update_issue, create_project, create_comment, create_issue_label), plus search_documentation.
• Clients: Claude (Connectors), Cursor, VS Code, Zed, Windsurf, Codex, Jules, v0. Multi-workspace needs separate auth contexts; subject to the underlying GraphQL rate limits.

GraphQL API

• Endpoint: https://api.linear.app/graphql (introspection supported). This is a GraphQL API — no REST.
• Auth: personal API key → Authorization: <API_KEY> (raw, no Bearer prefix); OAuth 2.0 → Authorization: Bearer <token>; app tokens for the agent/app-actor flow.
• SDK: @linear/sdk (TypeScript, fully typed). Mutations like issueCreate (input title/description/teamId), issueUpdate, agentActivityCreate.
• Rate limits (leaky bucket):

• Max complexity of a single query: 10,000 points (a larger query is always rejected). Headers: X-RateLimit-Requests-*, per-endpoint X-RateLimit-Endpoint-*, and X-Complexity / X-RateLimit-Complexity-*.
• Pagination: cursor-based Relay-style (first/after, pageInfo).
• Webhooks: subscribe to data-change events; agent events use AgentSessionEvent; team-access revocation emits PermissionChange.

---

7. Metrics — exact definitions

Linear's native analytics is Insights (Business/Enterprise only), reached via the right-sidebar panel (Cmd/Ctrl+Shift+I) on team, project, cycle, and Custom Views. Most powerful on workspace-level Custom Views, which pull across all teams. An Insight = a Measure grouped by a Slice, optionally colored by Segments.

Measures and their exact definitions:

• Issue count — number of issues (bar).
• Effort — total estimate value (bar).
• Cycle Time — issue start → completion (entered a Started status → Completed); scatterplot.
• Lead Time — issue creation → completion; scatterplot.
• Triage Time — duration spent in Triage; scatterplot.
• Issue Age — time since creation; scatterplot.

Note Linear's exact definitions: cycle time = start → done; lead time = created → done. (Some agile tools define lead time differently — do not assume.) "Throughput" is not a named measure — it's captured via Issue count / Effort over time (burn-up) and cycle velocity.

Chart types: bar (count/effort), scatterplot (time measures), and burn-up / cumulative-flow (how work streams changed over time; monthly by default). Export: hover for exact values, select to filter, copy share link, or CSV.

Cycle metrics specifically:

• Progress = by estimate points if estimates are enabled, else by issue count; un-estimated issues use the team default (or 1).
• Velocity = issues/points completed across the previous 3 completed cycles; a capacity dial on upcoming cycles predicts completion likelihood.
• Rollover (Autopilot): open issues auto-carry to the next cycle; anything moved to Backlog/Triage/Canceled/Completed does not.
• SLAs (Business+): auto-apply deadlines by rule; a fire icon escalates gray → yellow → orange → red; first matching rule wins; subscribers notified 24h before breach and at breach; outcome recorded as Achieved or Failed. Default rules: Urgent → 24h, High → 1 week.

---

8. Roles and permissions

• Workspace Owner (Enterprise) — full control: billing, security, audit logs, exports, OAuth approvals; configures which roles perform workspace-level actions. Managed via a linear-owners group on new Enterprise setups.
• Admin — routine workspace administration; manage/suspend members. On the Free plan all users are Admins; on Business/Enterprise, Admin is narrower than Owner.
• Member — standard collaboration across accessible teams; cannot reach workspace-level admin pages.
• Guest (Business & Enterprise only) — access only the issues/projects/documents of teams they're explicitly added to; cannot see workspace-wide features, customer requests, initiatives, or Code Intelligence. Only team owners add guests. Guests are billed as regular members.
• Teams — public or private; private teams hide their content entirely from non-members. Team owners manage labels, templates, settings, membership.
• Enterprise identity — SAML/SSO and SCIM provisioning (IdP-managed membership); SAML/Okta also backs MCP managed auth.
• Agents are installed apps, not users — they hold scopes (app:assignable, app:mentionable, customer:*, initiative:*) but never admin scope, and don't consume a seat.

Two changes worth holding (2026):

• Third-party app approvals (September 2026, paid plans) — admins review and approve apps before they can be installed. An integration that used to install itself may now sit waiting for an admin.
• Enterprise-managed authorization for MCP (August 2026) — on Enterprise workspaces with Okta SAML configured, Linear verifies identity through Okta and applies that person's existing Linear permissions to their MCP session. MCP access stops being a separate grant and becomes an extension of the IdP.

Initiatives can be led by a team, not only a person (August 2026). An initiative led by a private team is visible only to that team's members — a visibility rule that applies at the strategic layer, where previously privacy was a team-and-below concern.

---

9. Cycles vs Projects vs Initiatives — the containment model (and where Releases sit)

Because this is Linear's most load-bearing (and most-confused) area, stated explicitly:

An issue in a cycle and a project is normal and expected. A Project Milestone is an in-project checkpoint, not a release tag and not an initiative.

Release sits outside this table on purpose. It is not a container you plan into — it is a record of deployment, written by CI/CD. An issue is not "added to" a release the way it is added to a cycle or project; it appears in one because its code shipped. Two consequences: a release has no rollover and no membership rule to reason about, and "what is in the next release" is a question about deploy state, not about planning. Since April 2026 a Project Milestone and a Release are both easy to mistake for the other — the milestone is a plan, the release is a fact.

---

10. Hard limits and constants (quick reference)

Current plan names: Free · Basic · Business · Enterprise (paid plans billed annually).

Other constants:

• Sub-teams: up to 5 levels deep (inherit parent workflow/cycles/labels).
• Cycles: length 1–8 weeks; up to 15 future cycles pre-creatable; velocity from last 3 completed cycles.
• Label groups: one level of nesting; up to 250 labels per group; single-select within a group (one label per group per issue).
• Priority: 5 fixed values (0–4). Estimate scales: 4, base tops out at 5 values (+2 extended).
• GraphQL: 5,000 req/hr; 3M (API key) / 2M (OAuth) complexity pts/hr; 10,000 max single-query complexity.
• Reserved label names (cannot be used): assignee, cycle, effort, estimate, hours, priority, project, state, status.
• Release pipelines: 15 on Business, unlimited on Enterprise. Releases are not available on Free/Basic.
• Coding-session sandbox: $0.25 per 20-minute block, plus provider token rates at no markup. Spend limits are settable per workspace and per user, resetting daily, weekly, or monthly; usage pauses at the limit.
• Loops: Business+ only; metered in AI credits per run. Introductory credits were extended to December 31, 2026 — a promotional state, not a permanent allowance.

Issue identifier scheme: TEAM-123 = team key (usually 2–4 uppercase letters) + a per-team sequential integer. Moving an issue to another team assigns a brand-new identifier (new team key + that team's next number); the old ID/URL still resolves via redirect. IDs are effectively never reused within a team. IDs embedded in git branch names / PR titles are case-sensitive for matching.

---

11. Integrations

• GitHub / GitLab — copy a git branch name from an issue (Cmd/Ctrl+Shift+.); embedding the issue ID auto-links the PR. Closing magic words (close/closes/fix/fixes/resolve/resolves/implements/… + ID) auto-transition the issue to done on merge; non-closing words (ref/part of/related to/…) link without completing; skip ENG-123 suppresses. PR-status automations (Team → Workflows & automations) trigger on drafted/opened/review-requested/ready/merged, with branch-specific regex rules (e.g. merge to staging → "In QA"). GitHub Issues Sync mirrors title/description/status/assignee/labels/sub-issues/comments.
• Slack — issue creation via message action, the @Linear agent (natural language), or /linear; bidirectional synced threads; team/project/initiative notifications; rich unfurls with inline actions.
• Customer-feedback tools — Intercom, Zendesk, Front, Salesforce (Enterprise), plus Slack and Asks feed Customer Requests (see §12/§13).
• Others — Figma, Sentry; preview links (Vercel, Netlify, Cloudflare, Amplify) auto-attach to PRs (expire after 30 days of inactivity).
• Asks — Slack-based intake (Business+): turns Slack messages (and Enterprise web forms) into Triage issues with synced threads and templates; lets non-Linear users submit requests.
• CI/CD, via Releases (April 2026) — deploy pipelines report environments and versions into Linear, which is what lets a Release move issue status on production deploy (§4.1). This is the only integration class that writes issue status without a person or a magic word.
• Rich previews in diffs (September 2026) — images, fonts, Markdown, and PDFs render inside Linear diffs; symlinks show as file-based changes.

---

12. Gotchas an agent will otherwise get wrong

• Moving an issue to another team changes its ID. ENG-42 → DES-88; the old ID/URL redirect but the canonical ID is new. Never assume an ID is stable across a team move.
• Cycle ≠ Project ≠ Initiative ≠ Release. Cycle = time-boxed team sprint; Project = cross-team outcome; Initiative = strategic grouping of projects; Release = what actually shipped, written by CI/CD rather than planned into (§9). An issue can be in a cycle and a project at once, and separately appear in a release.
• A Release can move an issue's status on its own. When linked code lands in production the issue status advances — no magic word, no person. If an issue is "done" and nobody did it, check whether a deploy did (§4.1).
• Sub-issues can live in a different project/team than their parent. Parent-child is a relationship, not containment — don't assume inheritance of team/project. (Sub-issues do inherit parent priority/project on creation, but not labels, and can diverge afterward.)
• Completed vs Canceled are opposite in metrics. Both are "closed," but Completed counts toward progress and Canceled is excluded. Duplicate is a separate system status (Canceled type), auto-applied, un-renamable.
• Triage vs Backlog. Triage is an inbox for un-accepted incoming work; Backlog is a workflow status for accepted-but-not-started work. Neither rolls over into cycles.
• Rollover only carries open/started issues. Moving something to Backlog/Triage/Canceled/Completed drops it from the next cycle.
• Turning estimates on/off changes reported completion %. Progress is by points when estimates are enabled (with defaults filling un-estimated issues), by issue count otherwise.
• Auto-close on PR merge depends on config. Magic words in the PR / issue ID in the branch drive it, with conditions like "only when merged to main." Merging any linked PR does not necessarily close the issue.
• The Free 250-issue cap counts active issues only. Archiving frees the count; archived issues stay searchable and can be included in Insights via a toggle.
• Private team content is invisible to non-members. An agent without team membership cannot see or query a private team's issues/projects at all.
• Priority numbers are enum identities, not magnitudes. 1 = Urgent (highest), 4 = Low; "No priority" = 0 and sorts first or last per a team setting.
• Don't map Jira 1:1. Linear intentionally lacks per-issue-type custom workflows, a schemes system, and a separate "sprint" object (it's a Cycle). Trying to reproduce Jira constructs will fail.
• The agent 10-second rule. On a session created event, an agent that doesn't emit an activity within 10 seconds is marked unresponsive.
• Loops change workspace state with no human actor. A scheduled or event-triggered Loop can create issues, edit documents, and post to Slack (§4.7). Before attributing a change to a person, check the actor. Loops are auditable per run, which is where to look.
• Coding sessions cost money per minute of sandbox, not per task. $0.25 per 20-minute block on top of token cost. A session that sits waiting still burns runtime, which is why spend limits exist and why hitting one silently pauses AI usage rather than failing loudly.
• "Low configuration" no longer describes the whole product. It still holds for issues, statuses, and cycles. It does not hold for Loops, coding-session environments, spend limits, release pipelines, or app approvals — all of which a workspace configures and can misconfigure.
• Initiatives led by a private team inherit that team's privacy. A workspace-level object can now be invisible to most of the workspace (§8).

---

13. Vocabulary quick reference

Terms whose Linear meaning differs from generic agile, or that are Linear-specific:

• Workspace — the top-level company container (all teams, projects, initiatives).
• Team — the primary org unit; owns its own workflow, cycles, triage, labels; can nest into sub-teams (5 levels).
• Team key / identifier — the short uppercase prefix (e.g. ENG) in issue IDs and branch names.
• Issue — the fundamental unit of work; belongs to exactly one team.
• Sub-issue — a child issue; may live in a different project/team than its parent.
• Cycle — Linear's word for a sprint (repeating 1–8 week team period). Use "Cycle," not "Sprint."
• Cooldown — the optional buffer period between cycles.
• Project — an outcome-scoped body of work with a target date; can span teams.
• Project Milestone — an in-project checkpoint (not a release tag).
• Initiative — the strategic layer grouping projects (formerly "Roadmaps"); supports sub-initiatives.
• Triage — the per-team intake inbox; a special state type.
• Workflow — the team's ordered set of issue statuses (Linear's term; distinct from "automations," which are separate rules).
• State / status types — the five fixed buckets (Backlog / Unstarted / Started / Completed / Canceled) + Triage + Duplicate; custom status names map to a type.
• Estimate — the effort value; scales Exponential / Fibonacci / Linear / T-shirt; un-estimated defaults to 1.
• Priority — the fixed 5-value enum (No priority 0 / Urgent 1 / High 2 / Medium 3 / Low 4).
• View — a saved, filtered lens over issues/projects/initiatives; Custom Views can be workspace-wide and cross-team.
• Insights — the native analytics/charting feature (Business+).
• Customer Request — a captured piece of customer feedback linked to an issue/project; can attribute revenue and tier.
• Ask — the Slack/web intake surface turning external requests into Triage issues (Business+).
• Snooze — temporarily remove an issue/notification from view until a chosen time.
• Delegate (to agent) — assign an issue to an AI agent while the human teammate stays primary owner.
• AgentSession / activity types — the lifecycle (6 states) and emitted activities (thought/action/response/elicitation/error) of an agent working an issue.
• Autopilot — the automatic rollover of unfinished issues to the next cycle.
• Pulse — the AI digest of project/initiative updates (text or audio).
• Release — the deployment record (April 2026): environments, versions, and deploy status fed by CI/CD; moves issue status when code reaches production. Not a planning container.
• Release pipeline — one configured deploy path feeding Releases; 15 on Business, unlimited on Enterprise.
• Loop — a recurring Linear Agent workflow, triggered by a schedule or by workspace activity; Business+, metered in AI credits, auditable per run.
• Coding session — the agent's execution unit: a detected environment, a run, browser testing with before/after screenshots, then a PR. Billed as provider tokens plus $0.25 per 20-minute sandbox block.
• Project composer / draft project — a project developed with the agent before it exists as a live project (September 2026).
• Priority inbox — the Inbox's Priority tab, separating urgent notifications from the rest; Linear picks the default contents, the user can customize (September 2026).
• Callout — a colored, icon-marked block in issue and project descriptions; GitHub converts them to matching types in PR descriptions (September 2026).
• Spend limit — a workspace- or per-user cap on AI credit usage, resetting daily, weekly, or monthly; hitting it pauses usage rather than failing.