Operating Instructions

A complete user guide. For concepts, see Introduction.

Account

Sign up and sign in

Register at eastagiletracker.com/register with email and a password, or continue with GitHub if you prefer OAuth. Verify your email from the link we send; until then you can sign in but some features are limited.

If you’ve been invited to a project or an organization, follow the link in the invitation email — your account is created (or you sign in) and you land directly on the matching board.

Forgot your password? Use Forgot Password on the sign-in page; we email a reset link.

Account settings

From the avatar in the top right → Account Settings:

• Profile — Display name, initials (used in owner avatars), email.
• Bio — A short self-description (up to 4 KiB). Appears on /me and on org members listings so an agent (or a teammate) can pick the right person to ask. Leave it blank to opt out.
• Password — Change it any time.
• Avatar — Upload an image, or fall back to your initials.
• API Keys — Create personal API tokens; see API Guide.
• Theme — Agile, Labs, Dark, or Light (also switchable from the sidebar).
• Delete Account — A two-step confirmation. Removes you from all organizations and projects.

Security

From the avatar in the top right → Security:

• Two-factor (TOTP) — Set up a code from any authenticator app (1Password, Authy, Google Authenticator, …). Get 10 one-shot recovery codes — they’re shown once, so save them. Disable later with either a current code or a recovery code.
• Passkeys — Add a device-bound WebAuthn passkey (Touch ID, Windows Hello, hardware security key). Sign in passwordlessly afterwards. Add, name, and remove keys from the same page.

Sessions and refresh tokens

A successful sign-in mints two tokens: a short-lived access JWT and a long-lived refresh token (30 days, rotated on every use). The SPA refreshes the access token automatically when it expires; you stay signed in until the refresh token expires or you sign out. Sign-out revokes the refresh token server-side, so a stolen copy can’t be replayed.

Billing

Most accounts are Free Forever for personal use. If your account has a metered credit balance, find it under Account → Billing — top up via the Paddle checkout, see transaction history.

Organizations

Every account belongs to one or more organizations. A fresh sign-up gets a personal org (“<Name> Org”) auto-created in Linear/Vercel fashion. Projects live inside orgs, and org membership gates project membership.

Switch organization

Click the org switcher in the topbar to flip between orgs you belong to. The active org tints the sidebar, scopes the “Projects” list, and pre-selects when you create a new project.

Manage an organization (admin)

Click the org block in the sidebar → Manage organization → you land on /organization/{id}/projects. The sidebar surfaces three admin tabs:

• Projects — All projects in this org.
• Members — Current members, roles, and pending invitations. Invite by email; the invite is email-pinned with a TTL token and a role ceiling (members can’t invite admins).
• Settings (owners only) — Org name, slug, plan. Transfer ownership to another member here.

Remove a member

Removing a member from an org cascades: their per-project memberships in that org’s projects are revoked in the same transaction. Bookmarked board URLs stop working the moment they lose org access — there’s no orphan trail.

Projects

Create a project

From the Projects page, click New Project. The create form only asks for two things:

• Title — Required.
• Description — Optional; visible to all members.

Everything else — iteration length, start day, initial velocity, estimate scale, done state, task toggle — is set later in Project Settings and is seeded with sensible defaults.

Project settings

Under the project’s Settings menu, four tabs:

• Project — Edit title, description, iteration length and start day, velocity strategy (average of last 3 / 5 / 10), done state, estimate scale, task toggle.
• Member — Invite, promote/demote, and remove human members (see Members and invitations, below).
• Agent — Mint and revoke agent API keys for this project (see Agents, below). Owner-only.
• Import — Bring stories in from another tracker (see Importing from other trackers, below).

Members and invitations

In the Member tab of Project Settings, invite humans by email. Pending invitations sit in a separate bucket until accepted; you see who’s invited and can resend or revoke. Active members can be promoted/demoted between viewer, member, and owner. Owners can change project settings; viewers can read but not write.

Project history is on its own page — every change to project settings, every membership change, with the actor (human or agent).

Stories

Create a story

Use the + Add story affordance on any board panel (Current, Backlog, Icebox, or a custom one) — type a title and press Enter.

New stories created in Current default to current_state = 'unstarted'. That’s PT parity: a Current iteration is a plan of work, not a partition by state. The owner explicitly Starts the story when they begin the work — the cycle-time clock doesn’t kick off until then.

Required: title. Pick a type (defaults to feature). Add description, estimate (features only), labels, owners, followers, blockers — any of these can be filled in later from the detail panel.

Press Enter twice quickly? No problem — the button is guarded; you get exactly one story.

Estimate features

Features are the only type that takes points. Click the points circle on a card (or in the detail panel) and pick from the scale. Unestimated features show a blank circle.

• Fibonacci scale — 0, 1, 2, 3, 5, 8, 13. Standard XP. Anything bigger than 13 should be split into smaller stories.
• East Agile scale — 0, 1, 2, 3. Tighter. A 3 means a full iteration of one person’s time. Nothing fits past 3.
• 3-Point scale — 1, 2, 3 (Small / Medium / Large). Strict t-shirt sizing — no zero option, no half-points.

Pick the scale once in Project Settings; you can change it later (existing estimates map across).

Advance state

Three ways to move a story through the lifecycle:

1. Click the inline action button on the card — Start, Finish, Deliver, Accept, Reject. The button text reflects the next valid state for the story’s type.
2. Drag the card to a different column. The system applies the transition that crossing that column implies. Backward moves prompt for confirmation.
3. Bulk transition — Select multiple stories, Transition all — each story transitions independently. If one is illegal, the others still go through.

Detail panel

Click anywhere on a story row to expand it inline. The detail panel shows:

• Title (editable), description (Markdown), type, estimate, requestor.
• Owners (add/remove members or agents), followers, labels.
• Tasks (if enabled), comments, attachments, blockers, links, reviews.
• A 3-dot menu for duplicate, delete, and other less common actions.

Press Escape to close the most recently opened story (it remembers the stack — collapse one at a time).

Comments

Up to 10,000 characters, Markdown rendered. Edit and delete your own comments; the audit log keeps the history. @-mention members and the autocomplete picks them up.

Attachments

Drag a file onto the detail panel, or use the upload button. Up to 2 GB per file — yes, big enough for screen-recording video walk-throughs. Use the video player inline.

Labels

From the Labels page in the sidebar: create labels with names and colors, archive when stale (archived labels disappear from the board but stay searchable). Add labels per story in the detail panel.

Blockers, links, reviews

• Blockers — A free-text “this is blocked by X” note. Mark resolved/unresolved. Filter the board by has:blocker.
• Links — Six relationship types: relates to, duplicates, blocks, is blocked by, pull request, branch. Paste a GitHub URL and the type is auto-detected.
• Reviews — Assign a reviewer (human or agent) with a status (pending, approved, rejected) and optional comment.

Tasks

If enabled in Project Settings, stories get sub-tasks — a checklist inside the story. Check them off as you go; the count appears on the card.

Story field reference

Every choice variable on the story-detail surface carries a small [?] icon next to its label. Click it in-app to see the same guidance summarised below. Translators ship the in-app copy alongside the rest of the UI; this section is the long-form canonical reference.

The fields are listed in the order they appear in the Overview tab.

Status

The story’s place in the lifecycle: Unstarted → Started → Finished → Delivered → Accepted (or Rejected back to Started).

The critical state is Delivered: the engineer marks it delivered, but it isn’t done until the product owner explicitly Accepts it against the acceptance criteria — or rejects it, kicking it back. This bakes a customer-feedback loop into every story rather than deferring acceptance to a sprint-end demo.

If stories pile up in Delivered, that’s a signal the accept/reject loop has stalled. Look at the Delivered count at the end of every iteration — if it’s growing, that’s your signal that the product owner is under-resourced or the acceptance criteria aren’t clear enough up-front.

Iteration

Which iteration the story is planned into. Leave it as None to keep the story in the Backlog, where the system will auto-group it under an upcoming iteration based on velocity.

Manual override here is useful when you want to pin a story to a specific iteration regardless of order — e.g. tying a release story to a fixed date. Otherwise let the order in the Backlog drive iteration assignment; that’s what keeps the velocity projection honest.

Owners

Who’s doing the work. Owners can be humans or agents — both render as named participants in the audit log, comment authorship, and analytics. There is no way to disguise an agent owner as a human.

Multiple owners is the visible expression of pair programming (or pair-with-agent). Add the agent that picked the story up and the human reviewing — both names appear on the card. This keeps work-in-progress low; finishing before starting the next story is the single biggest lever on cycle time.

Owners are not the same as Followers (a separate field on the card). Followers are people who care about the story but aren’t doing the work — typically subscribers to notifications.

Story type

The four types are not interchangeable — the distinction is the whole point of the data model.

• Feature — New user-observable value. The only type that carries points and counts toward velocity. This forces you to slice work into value the user can see.
• Bug — A defect. Unpointed. Defects don’t earn velocity credit, which keeps rework cost visible rather than rewarded.
• Chore — Necessary work with no direct user value (refactors, infra, setup). Unpointed. The team is pressured to bundle chores into features wherever possible so the value framing stays honest.
• Release — A zero-point marker for a milestone. Goes straight from Unstarted to Accepted, anchoring a date for the projection.

If you find yourself wanting to point a bug or chore: don’t. That breaks the projection that makes the whole system honest. Velocity is a measurement instrument; you don’t tamper with your own instrument.

Priority

Don’t use this if you can help it. The Backlog is the priority — top-to-bottom, single-priority, no ties. The product owner owns the order.

A “priority” field is the classic anti-pattern that quietly converts an empirical, ordered backlog back into wishful planning. If you find yourself with three P1s, you don’t have a priority — you have a Backlog with the wrong order. Fix the order; delete the priority signal.

The field exists for compatibility with imports from trackers that use one (Jira, Asana, …) so imported stories don’t lose information on the way in. Leave it on “None” in new work.

Points

Relative size of the story. Features get points; bugs, chores, and releases stay at zero.

Estimation is a sizing conversation, not a promise. Don’t translate points to hours; don’t inflate points to look fast. Velocity is a measurement instrument — you don’t tamper with your own instrument.

Three scales ship:

• Fibonacci — 0, 1, 2, 3, 5, 8, 13. The classic XP scale. Anything bigger than 13 should be split.
• East Agile — 0, 1, 2, 3. A tighter scale. A 3 means a full iteration of one person’s time.
• 3-Point — 1, 2, 3 (Small / Medium / Large). Strict t-shirt sizing.

If you’re often estimating in 5s, 8s, or 13s, your stories are too big. Split until each is independently deliverable (the S and the I in INVEST).

Requester

Who asked for the story. Usually one person — the product owner, a stakeholder, or an agent acting on someone’s behalf.

The requester is not the owner. The owner is whoever’s doing the work; the requester is whoever cares about the outcome and will (or won’t) accept it. They can be the same person, but they’re separate roles. Recording the requester is what gives you the audit answer to “who asked for this?” six months later.

Labels

Colored tags. Stories can carry multiple. Used for cross-cutting categorization — mvp, tech-debt, security, a particular release name — and for board filtering (label:mvp in the search box, or save it as a custom filter panel).

Labels are project-scoped. Manage them on the Labels page in the sidebar. Archive stale labels rather than deleting; the archive keeps history searchable while clearing the board.

Blockers

Free-text notes describing what’s preventing this story from progressing. Mark resolved when the impediment lifts.

Blockers are a flow signal, not a queue. Use the daily standup to surface them; resolve them out of band. If you have more than one or two open blockers per story for more than a day, the planning is wrong — split the story or change the dependency. The goal is for the Blocked panel to be mostly empty most of the time.

Description

What the story is and how to recognize it’s done. Markdown.

Acceptance criteria belong here — ideally in Given / When / Then form so they map directly onto acceptance tests:

Given I am signed in as a member
When I click "Add a story" in Current
Then the story is created in state "unstarted"

INVEST is the sanity check on whether a story is well-formed:

• Independent — can be released without other stories.
• Negotiable — captures intent, not a frozen spec.
• Valuable — to a user or stakeholder.
• Estimable — the team can size it.
• Small — fits comfortably in an iteration.
• Testable — has acceptance criteria that can be exercised.

A story at the top of the backlog with vague acceptance criteria is a planning bug — not a future problem to ignore. Fix it before letting it advance.

Bulk actions

Select multiple stories on the board (shift-click range, or Select all in panel). Then:

• Bulk transition
• Bulk delete
• Bulk duplicate

The board

The board is the home screen of each project. Three columns by default:

• Current — Stories in the active iteration. Grouped by iteration header (current, then upcoming, then closed). Cards appear in iteration time-sequence order with their state visible on each card; the column is not sliced by state — that breaks the iteration time-sequence the team plans in.
• Backlog — Strictly ordered queue. The system auto-groups upcoming iterations based on velocity. The product owner owns the top-to-bottom order; clarity is allowed to degrade as you scroll down, but never at the top.
• Icebox — Ideas without a date. Unordered, unestimated. The Icebox is allowed to be a graveyard.

Configurable panels — sidebar checkboxes

The sidebar’s Board section lists every preset column with a checkbox: tick a box to show that column, untick to hide. Toggles persist per-project per-user (they’re synced through GET/PUT /preferences). The presets are:

• Current Iteration (on by default)
• Backlog (on by default)
• Icebox (on by default)
• Done — Accepted stories.
• My Work — Stories where you’re an owner.
• Blocked — Stories with unresolved blockers.
• Epics — Epic-level rollups.
• Chat — Project-scoped chat column.

Custom filter panels

Pin a search as a panel: paste a query like type:feature label:mvp owner:claire, save it. Resize columns to suit; widths persist across sessions.

Search

The search bar accepts the filter syntax described in Introduction. Search results live in a results panel; click any to jump to it on the board.

Current-iteration chip

The top bar shows the current iteration number, date range, and points accepted vs planned. Click to jump to the Current column.

Iterations

The system creates iterations automatically based on your length and start day. You don’t need to “open” or “close” them.

To plan ahead, drag stories from the Backlog into upcoming iteration groups. The system marks groups red if they exceed your velocity. To plan further out, scroll the backlog — it shows three or four iterations ahead.

To rewind: click any past iteration header in the Current column to drill into the iteration report.

Releases

Releases are a story type, not a separate object. Create a release the same way you’d create any story: pick Release as the type, give it a name (e.g., v2.4), drag it into the iteration where you intend to ship.

Releases skip the Started/Finished/Delivered/Rejected states — they go from Unstarted to Accepted in one step. Accept a release when you ship; the analytics views display the release marker.

Analytics

The Analytics tab (top of the project) gives you six reports:

• Project Overview — Velocity trend, recent iteration KPIs, burnup, burndown, cumulative flow.
• Iteration — Drill into a single iteration: KPIs, burndown, state flow.
• Releases & Burndowns — Release timeline, burndown per release.
• Story Activity — Who did what, filterable by actor, type, date range.
• Cycle Time — Mean and distribution of time from Started to your done state.
• Projections — Forecast for when the backlog will be done at current velocity.

Agents

This is the part of the product that sets it apart. An agent is a named teammate — but it’s an AI.

Add an agent to a project

You must be a project owner (or admin). Open Project Settings → Agents:

1. Create new agent key.
2. Give the agent a name (it will show up as that name in audit logs, comment authorship, and owner avatars).
3. Pick a role — viewer (read-only) or member (can write). Owner role is restricted to humans.
4. The key is shown once — copy it; we don’t store it retrievably. The prefix is ea_agent_….

What agents can do

An agent with member role can do anything a human member can:

• Create, edit, transition, delete stories
• Comment, attach files, add labels, set owners
• Pick itself as owner of a story
• Read activity, follow events

The audit log records every write with the agent’s identity. There is no way to make an agent action look like a human action.

Manage agent keys

In Project Settings → Agents you see all active keys, their names, roles, and last-used timestamp. Revoke a key any time; the agent loses access immediately. The agent’s past activity stays in the audit log forever.

Use agents with the API

See API Guide → Agent keys for code examples.

Importing from other trackers

If you’re coming from another tool, we have importers for eight sources:

• Pivotal Tracker
• Jira
• Asana
• GitLab
• Shortcut
• Trello
• Linear
• Plane

From Project Settings → Import, upload an export (CSV from most, JSON from Plane). Stories, owners, comments, labels, and states map automatically; some sources also bring iterations.

A preview shows what will be imported. Mismatches (e.g. a label not in your project) prompt — create-or-skip, your choice.

Themes

Four themes ship. Switch in the sidebar footer (or in Account Settings → Theme):

• Agile — The marketing landing-page palette. Warm whites, deep-blue brand accent (#1f6f9f), saturated story-type icons. Lead option in the switcher.
• Labs — The Pivotal Tracker palette, lovingly preserved. Dark chrome, blue topbar, pastel column gaps. The original.
• Dark — Pure neutral dark.
• Light — Pure neutral light. Ink on paper.

Your theme persists across sessions.

Language

The UI is translated into 15 languages: English, French, German, Spanish, Japanese, Chinese, Korean, Portuguese, Italian, Dutch, Swedish, Danish, Czech, Finnish, Polish. Switch from the sidebar footer — the chrome, auth pages, account/security area, project list, and marketing landing localize immediately. Story-detail / analytics / settings localization is following.

Keyboard shortcuts

A few that earn their keep:

• Escape — Collapse the most recently opened story.
• Enter in an inline input — Submit (won’t collapse the row).
• Shift-click — Range-select stories.

More are added over time; see Help in the sidebar for the current list.

Self-hosting

East Agile Tracker is open source. The full source is at github.com/EastAgile/agile-tracker — clone it, build it, run it on your own infrastructure. Same feature set as the hosted version.

For setup, see the project README.