# Stella Loop — complete documentation
> Stella Loop is an agent-native project management tool for loop-based, iterative software development — an alternative to traditional trackers, built for teams where humans and coding agents ship together. The hosted app is at https://app.stellaloop.com. This file collates the entire documentation (24 pages) and the tracker comparison into a single document for agents; a quick-orientation version lives at https://stellaloop.com/llms.txt.
Site: https://stellaloop.com · App: https://app.stellaloop.com · Docs: https://stellaloop.com/docs/ · Contact: stella@lorenalabs.com
Contents: What is Stella Loop · Getting started · The loop · North Star · Signals · Intents · Analysis · Proposal pool · Epics and tasks · Plan · Review · The loop engine · Provenance · Agents · CLI · API · MCP · Web app · Desktop app · GitHub integration · Signal connectors · Notifications · Glossary · FAQ and limitations · Stella Loop vs Linear-shaped trackers
---
# What is Stella Loop
Getting started · https://stellaloop.com/docs/what-is-stella-loop/
Stella Loop is an agent-native project management tool for loop-based, iterative software development — an alternative to traditional trackers, built for teams whose development work is increasingly carried out by and alongside coding agents.
The name describes the model. Every project declares a **North Star constellation** — a set of documents and tenets describing what the product should become — and the tool's job is to continuously pull the product toward that aim. Work is not a one-way flow of hand-written tickets; it is a repeating **loop** of analysis, proposal, planning, implementation, and review, with 0–100 scores that make progress measurable rather than anecdotal.
## The problem it solves
Traditional trackers assume humans invent the work: someone notices a problem, writes a ticket, and the tool manages the ticket's states. That model breaks down in two ways:
1. **Discovery is unmanaged.** Where work *comes from* — noticing gaps, assessing quality, deciding what matters next — happens outside the tool, so priorities are anecdotal and unrepeatable. Stella Loop makes discovery a first-class, tool-managed half of the lifecycle: signals capture what the world tells you, intents drive analyzer runs over the actual codebase, analyzers produce scored reports, and reports yield proposals that compete in a pool before anything is committed.
2. **Agents are bolted on.** Coding agents can execute tickets, but most tools give them no native way to discover work, read context, or report results. In Stella Loop, agents are first-class users: every capability a human has in the UI is available through the `stella` CLI, the public API, and a generated MCP server — and that parity is checked in CI, not promised.
## Who it is for
- **Product managers and developers** get a dense, keyboard-first, command-palette-driven interface with realtime liveness — running loops, working agents, and moving scores are always visible.
- **Coding and analysis agents** drive the identical model through the `stella` CLI (self-discoverable from `--help` alone), the `/api/v1` HTTP API beneath it, and an MCP server generated from the same capability map.
## How it differs from an issue tracker
- **Work has provenance, not just a reporter.** Every epic traces back through proposal → report → intent — and, through signals, onward to the external message that motivated it.
- **Commitment is a modeled moment.** Epics are born only by promotion out of the proposal pool. There is no direct "create epic" path in the UI, the API, or the CLI.
- **Quality is a number.** Analyzers score the codebase 0–100 overall and per area, with versioned rubrics so runs stay comparable.
- **Loop-backs are modeled, not improvised.** Review can send work back to implementation (fix) or back to planning (re-spec), and learnings from finished work seed the next intent.
- **Alternatives can race.** Competing proposals can be promoted as a tournament: one epic, one candidate per approach, each on its own branch, with review selecting the winner.
- **The pipeline is opinionated; the tooling is pluggable.** The loop shape is the product's opinion. Spec tools (OpenSpec is the default), analyzers, and version control (git by default, Jujutsu supported) sit behind adapter interfaces.
## Product surfaces
One backend, one interface model, several clients:
| Surface | What it is |
| --- | --- |
| Web app | The hosted app at app.stellaloop.com — dense, keyboard-first, realtime, designed for desktop-class screens |
| Desktop app | A native macOS app wrapping the same interface, with tray presence, global shortcuts, native notifications, deep links, and offline reading |
| CLI | `stella` — the primary agent surface; a thin client over the public API |
| API | `/api/v1` — API keys, OpenAPI self-description, webhooks, and a realtime event feed |
| MCP | `stella mcp serve` — tools generated from the same capability map as the API |
## Where to go next
Start with [Getting started](https://stellaloop.com/docs/getting-started/) to run your first loop, or read [The loop](https://stellaloop.com/docs/the-loop/) to understand the model end to end. Setting up a coding agent? Go straight to [Agents](https://stellaloop.com/docs/agents/).
---
# Getting started
Getting started · https://stellaloop.com/docs/getting-started/
This guide takes you from a fresh workspace to your first completed loop. You will connect a repository, set a North Star, fire an intent, watch analysis produce evidence, promote a proposal into an epic, and see the loop close.
## 1. Create your workspace
Sign in at [app.stellaloop.com](https://app.stellaloop.com) and create an organization, then a project inside it. A project is the loop's home: it holds your linked repositories, your North Star constellation, your analyzer registry, and your proposal pool.
Two things worth doing immediately:
- Press ⌘K (or Ctrl K) to open the command palette. Every action in Stella Loop is reachable from it.
- Press ⌘⇧S anywhere to capture a signal — a thought, a bug, a request. You will triage these later; capture is deliberately instant.
## 2. Connect a repository
In organization settings, open **GitHub** and install the Stella Loop GitHub App on the account that owns your repositories. Then, in project settings → **Repositories**, link one or more repositories to your project. For each repository you choose the version-control workflow: git (the default) or Jujutsu.
From the moment a repository is linked, newly arriving GitHub issues flow into your [signals](https://stellaloop.com/docs/signals/) queue, and branches, pull requests, and checks mirror into the project in realtime. See [GitHub integration](https://stellaloop.com/docs/github-integration/) for the details.
## 3. Set the North Star
Open **Constellation** and create your first North Star documents. Three ways in:
- Start from a template — product, design, engineering, and agent-experience types ship with starting points.
- Import from a repository — an existing `VISION.md` or principles document can be imported once or kept in sync from git.
- Start blank.
Activate a document to make it part of the live aim (activation pins a citable version). Set per-document weights if some concerns matter more than others — per-document scores roll into the composite through these weights. See [North Star](https://stellaloop.com/docs/north-star/).
## 4. Fire your first intent
Open **Intents** and create one. Pick the archetype that matches your situation:
- **Directed** — you know the work: "Add CSV export". Defaults to targeted analysis such as feature pre-scoping.
- **North Star-driven** — you want the evidence to decide: "Move us toward the aim". Defaults to a broad analyzer battery.
Submit it for approval, approve it, and it fires: the analyzers in scope fan out in parallel. Watch the run live on the intent's Analysis tab — each analyzer produces a report (`RPT-n`) with findings and scores. The built-in suite covers UX walkthrough, code quality, security review, feature pre-scoping, gap analysis, demand signals, and North Star satisfaction. See [Intents](https://stellaloop.com/docs/intents/) and [Analysis](https://stellaloop.com/docs/analysis/).
## 5. Prioritize and promote
When analysis settles, proposals are derived from the reports and land in the **Pool** — grouped into sibling sets where several approaches answer one problem. Reorder by priority (drag, or entirely by keyboard), link dependencies, and prune what you won't do (a reason is required — nothing disappears silently).
When a set is worth committing to, **Promote** it. Promotion is the commitment point: it creates the epic, and it is deliberately the only way an epic can be created. For sibling sets with genuinely divergent approaches, the promote dialog shows the engine's guidance on whether a [tournament](https://stellaloop.com/docs/epics-and-tasks/) — racing the approaches on real branches — is worth the spend. Out of the box, promotion requires a human's approval.
## 6. Plan, implement, review
The epic (`EPC-n`) moves through an explicit pipeline: **Plan → Implement → Review → Done**.
- **Plan** — each candidate is turned into a spec by the configured spec tool (OpenSpec by default) and decomposed into tasks. Approve the spec to hand off.
- **Implement** — tasks (`TSK-n`) are claimed by humans and agents. An agent's session is race-safe: claiming uses compare-and-swap with a lease, so two agents can never hold the same task. Point an agent at [`stella work list --ready`](https://stellaloop.com/docs/cli/) and it can drive itself.
- **Review** — a panel of reviewer agents (plus any humans you add) evaluates the work through explicit lenses. Verdicts are modeled edges: **fix** sends work back to implementation, **re-spec** reopens the plan, **accept** drives the ordered merge through the `epic.merge` gate.
When the merge lands, scores resolve on the dashboard, learnings are recorded, and seed intents are drafted from what was learned — the next loop is ready to start. If the epic began life as a signal, Stella Loop can post a resolution notice back to the original thread.
## 7. Dial in autonomy
Everything above ran with default gates: promotion and merge required your approval; most other transitions ran autonomously with an audit trail. As trust grows, open project settings → **Gates & autonomy** and move the dial — **supervised**, **balanced**, or **autonomous** — or configure individual gates. Standing intents with re-fire triggers (post-merge, on a schedule, on a score drop) make the loop turn continuously. See [The loop engine](https://stellaloop.com/docs/loop-engine/).
## Set up an agent
Every step above is equally available to an agent:
```
npm install -g @stella-loop/cli
printf %s "$STELLA_API_KEY" | stella auth login --with-key
stella project switch ATLAS
stella work list --ready
stella task claim TSK-214
stella context show TSK-214
```
Create the API key in settings → **API keys**. See [Agents](https://stellaloop.com/docs/agents/) for the full walkthrough, and [MCP](https://stellaloop.com/docs/mcp/) if your agent speaks the Model Context Protocol.
---
# The loop
Core concepts · https://stellaloop.com/docs/the-loop/
Development in Stella Loop is a loop, not a line. Every stage can feed back into an earlier one, and the output of finished work is the input of the next cycle. This page walks the lifecycle end to end; each stage links to its own page for depth.
## The shape
```
(Signals — the front door: outside world → captured, triaged input)
North Star constellation (the aim everything is pulled toward)
Intent (directed or North Star-driven)
└─► Analyse (analyzer runs → reports + scores)
└─► Propose (derive candidate solutions from reports)
└─► Proposal pool (prune · prioritize · sibling sets · deps)
└─ promote ══► EPIC created (the commitment point)
└─► Plan (spec → tasks)
└─► Implement ◄──────────┐
└─► Review ── fix ──┘
├─ re-spec ─► Plan
└─► Done (merge;
learnings seed
the next intent)
```
The lifecycle chains strictly: **intents give rise to analysis, analysis gives rise to proposals, promoted proposals give rise to epics, and epics give rise to tasks.** The intent is the container for the discovery half; the epic is the container for the delivery half; the proposal pool is the junction between them.
## Stage by stage
- **[North Star](https://stellaloop.com/docs/north-star/)** — not a stage but the loop's fixed point: a versioned, weighted, typed set of documents describing what the product should become. Analyzers cite the exact document version they scored against.
- **[Signals](https://stellaloop.com/docs/signals/)** — upstream of the loop. A signal is an uninterpreted observation — a GitHub issue, a Slack message, a Sentry alert, an email, a ten-second thought — captured with zero required structure and triaged into the loop's existing doors. Nothing signal-shaped becomes an epic or task directly.
- **[Intents](https://stellaloop.com/docs/intents/)** — every loop turn starts with an intent: a statement of aim that selects and scopes analyzers. Standing intents re-fire on triggers (manual, schedule, post-merge, score-drop), which is what makes the loop continuous.
- **[Analysis](https://stellaloop.com/docs/analysis/)** — analyzers examine the codebase and produce reports (`RPT-n`) with findings and 0–100 scores. Runs fan out in parallel; comparability is structural.
- **[Proposals and the pool](https://stellaloop.com/docs/proposal-pool/)** — candidate solutions derived from reports, grouped into sibling sets (competing approaches to one problem), prioritized before the expensive stage.
- **Promotion** — the commitment point. Promoting out of the pool creates the epic, atomically, through the `epic.promote` gate. Two modes: prune-first (promote one chosen approach) or tournament (race them all).
- **[Epics and tasks](https://stellaloop.com/docs/epics-and-tasks/)** — the delivery container. The epic's stage machine is Plan → Implement → Review → Done with explicit loop-back edges, enforced server-side.
- **[Plan](https://stellaloop.com/docs/plan/)** — each candidate becomes a spec (OpenSpec by default, pluggable) which is decomposed into tasks. The stage that warrants the strongest models.
- **Implement** — tasks are executed by coding agents and humans, with race-safe claiming and full context available to every implementer.
- **[Review](https://stellaloop.com/docs/review/)** — a reviewer panel evaluates the work. Three verdict directions: a **fix loop** back to Implement, a **re-spec escalation** back to Plan, or acceptance. In a tournament, review selects the winner. Review drives the coordinated merge.
- **Done — and the next turn** — merged work lands, learnings seed draft intents, standing intents re-fire on the merge, and the completed cycle is counted as a numbered loop iteration with a closing summary: score delta, epics shipped, learnings seeded, spend.
## The edges that make it a loop
- **Fix loop** (Review → Implement): review findings send work back without reopening the spec.
- **Re-spec loop** (Review → Plan): findings escalate past a fix and reopen the candidate's spec as a new revision.
- **Seed edges** (Review/Done → Intent): learnings and observations from finished work arrive in the intents list as seeded drafts — "Seeded from EPC-12 review learnings" — and enter the normal approval gate.
A one-way pipeline treats rework as failure. The loop treats it as the normal mechanics of getting something right, and models every edge explicitly so state stays honest.
## Provenance
Every stage's artifact carries immutable references to the artifact that motivated it:
```
epic → proposal → report → intent [→ signal → external source]
```
Display IDs make the chain legible everywhere: `SIG` (signal), `INT` (intent), `RPT` (report), `PRP` (proposal), `EPC` (epic), `TSK` (task). See [Provenance](https://stellaloop.com/docs/provenance/).
## Governance
The loop engine makes the stages one governed loop: a canonical stage-transition table every surface enforces, checkpoint gates on every consequential transition with a project-level autonomy dial, and model tiers and budgets that keep spend deliberate and visible. See [The loop engine](https://stellaloop.com/docs/loop-engine/).
---
# North Star
Core concepts · https://stellaloop.com/docs/north-star/
The North Star constellation is the live, versioned, weighted representation of your project's aim — the set of documents the whole loop pulls the product toward. It is a product object, not passive documentation: analyzers score against it, proposals cite it, and prioritization is justified by it.
## Documents
A constellation is made of North Star documents. Each document is a set of tenets typed by concern — the recommended types are **product**, **design**, **engineering**, and **agent experience**, and you can define custom types per project. Documents move through a simple lifecycle:
```
draft ── activate ──► active ── archive ──► archived ── restore ──► active
```
Only **active** documents form the live aim. Activation mints a version, so an active document always has a citable head.
## Versions
Documents are edited collaboratively in a rich editor (markdown in, markdown out — agents edit the same content over the API and their changes appear live in an open editor). Versions are minted explicitly, never per keystroke:
- **Save version** — an explicit save, with an optional message.
- **Activation** — activating a document with unsaved changes mints one.
- **Analysis** — when an analyzer is about to score against a document with unsaved changes, a version is pinned first, so every score cites an exact, immutable version.
- **Repo sync** — a synced document's version records the git commit it came from.
Version history includes server-computed diffs between any two versions, and any version can be restored.
## Repository import and sync
If your principles already live in git — a `VISION.md`, a design doctrine — import them. Two modes:
- **Copy** — a one-time import; the document becomes app-managed.
- **Sync** — the repository stays the source of truth. The document is read-only in the app, each push that changes the file mints a new version citing the commit, and sync failures are reported plainly on the document rather than going silently stale. You can detach a synced document later to make it app-managed, keeping its history.
## Weights and the composite
Each document carries a weight. Effective weights are normalized over the active documents, and per-document scores roll into the project's composite score through them — so if design matters more than engineering this quarter, the composite reflects that. Weight changes never mint versions, and each analysis run snapshots the weights it used so historical composites stay interpretable.
## Tensions
Sometimes two documents pull in opposite directions — "ship fast" versus "never regress accessibility". Stella Loop records that as a **tension**: a first-class object on the document pair, created by analyzer findings or by hand, with an open → acknowledged → resolved lifecycle and a required resolution note. Conflicts are surfaced, never silently averaged.
## Working with the constellation
| Action | Web | CLI |
| --- | --- | --- |
| Create a document | Constellation → New document | `stella northstar create` |
| Read content | open the document | `stella northstar show ` |
| Edit content | rich editor | `stella northstar edit ` |
| Save a version | ⌘S | `stella northstar save-version -m "…"` |
| Diff versions | Version history panel | `stella northstar diff ` |
| Activate / archive | document actions | `stella northstar activate\|archive ` |
| Set weights | Weights panel | `stella northstar weight ` |
| Manage tensions | Tensions panel | `stella northstar tension list\|record\|resolve` |
| Import from repo | Import dialog | `stella northstar import : [--sync]` |
Keyboard on the constellation surface: n new document, j/k traverse, e focus editor, w weights, t tensions.
## Where it flows
North Star-driven [intents](https://stellaloop.com/docs/intents/) reference constellation documents in their scope; [analysis](https://stellaloop.com/docs/analysis/) scores against pinned versions and rolls the composite through the weights; review's north-star lens grounds findings in your own doctrine; and every epic ultimately traces back to an aim expressed here.
---
# Signals
Core concepts · https://stellaloop.com/docs/signals/
A signal is an uninterpreted observation captured upstream of the loop — a bug report, a customer email, a Sentry alert, a teammate's Slack message, a ten-second thought. Signals are held with full provenance until triage decides what each one becomes.
Three guarantees define the vertical:
- **Capture is frictionless.** Title-only, never blocked by an approval, instant from anywhere.
- **Nothing is silently lost or rewritten.** Source payloads are kept as immutable, append-only snapshots; there is no hard deletion; every move is on the record.
- **Demand becomes evidence.** Triaged signals feed a cluster-weighted corpus that analysis consumes — "eleven people asked for CSV export" becomes a scored finding, not folklore.
## Capturing signals
- **In the app** — press ⌘⇧S anywhere, or run "Capture signal" from the palette. The composer defaults the project from your context and can attach the entity you were looking at.
- **From the CLI** — `stella capture "Export progress needs a visible state"`. In a linked repository's working directory, the project is inferred from the git remote.
- **From connectors** — GitHub Issues, Slack, Sentry, inbound email, and generic signed webhooks ingest automatically. See [Signal connectors](https://stellaloop.com/docs/signal-connectors/).
Every signal gets an org-scoped display ID (`SIG-n`) at capture, stable for life. Signals can arrive assigned to a project (from context or a connector rule) or land in the organization's unassigned bucket for routing.
## Triage
Triage gives each signal its altitude. The queue is keyboard-complete:
| Key | Disposition | What happens |
| --- | --- | --- |
| i | Seed intent | Creates a draft [intent](https://stellaloop.com/docs/intents/) carrying the signal as provenance |
| a | Attach as evidence | Attaches to an intent, epic, proposal, or North Star document — rendered in that item's Evidence section |
| m | Merge | Folds into a cluster as a duplicate, bumping the demand count |
| x | Dismiss | Declines, with a required reason |
| s | Snooze | Hides until a time you pick; a source update wakes it |
| p | Assign | Routes to a project |
Dispositions are reversible where reversal makes sense: dismissed signals can reopen, merged signals can unmerge, and a signal whose last attachment target goes away returns to pending — nothing dead-ends.
**Agent-assisted triage** is available and governed: a standing triage runner proposes actions with a rationale and confidence, and applying an agent suggestion passes the `signal.triage` gate under your project's autonomy dial. A human accepting a suggestion applies it directly as that human's act.
## Clusters and demand
Merging duplicates builds a **cluster** with a demand count — the weight of accumulated asks. The demand corpus (cluster-weighted, triage-aware, with dismissed signals excluded) feeds the built-in **demand signals** analyzer, which reports validated versus unvalidated demand and cites the `SIG-n` receipts behind every finding. Demand flows into the same reports-and-scores pipeline as every other analyzer, so it competes for prioritization on evidence.
## Resolution notices
When an epic ships, Stella Loop resolves the signals behind it — those that seeded the intent and those attached as evidence — and, where the connector has outbound replies enabled for the project, posts **one resolution notice, ever, per signal** back to the source: a comment on the GitHub issue, a Slack reply, an email. The default template is privacy-safe (no internal IDs or links). Signals captured in-app notify their capturing person through the [inbox](https://stellaloop.com/docs/notifications/) instead.
The provenance chain runs end to end: a support ticket is traceable to the merged change that resolved it, and the loop answers the person who asked.
## For agents
Signals have full CLI and API parity: `stella signal list|show|assign|snooze|seed-intent|attach|merge|dismiss` and friends, all under `/api/v1` with idempotency receipts on every mutation. See [CLI](https://stellaloop.com/docs/cli/) and [API](https://stellaloop.com/docs/api/).
---
# Intents
Core concepts · https://stellaloop.com/docs/intents/
Every loop turn starts with an intent: a first-class object that names the aim, selects and scopes analyzers, and acts as the container for everything upstream of the proposal pool. Intents are the root of the provenance chain — every epic ultimately answers "why does this exist" with an `INT-n`.
## Two archetypes
- **Directed** — you name the work: "Add CSV export". Directed intents default to targeted analysis such as feature pre-scoping, which maps what already exists before anything is built. Even hand-initiated features get analysis by default, so commitment always follows evidence.
- **North Star-driven** — you name only the aim: "Move us toward the constellation". These fan out a broad analyzer battery and let the evidence decide what gets proposed.
## Lifecycle
```
draft → awaiting approval → approved → analyzing → proposing → concluded
```
Submitting an intent emits the `intent.activate` checkpoint — whether a human approves, an agent with authority approves over the CLI, or policy auto-approves is decided by your [gate configuration](https://stellaloop.com/docs/loop-engine/). Once approved, firing the intent fans out its analyzers; when analysis settles, proposal derivation runs; when that completes, a standing intent re-arms and a one-shot intent concludes.
A failed run (every analyzer failed) re-arms the intent with the reason stated plainly — a failed run produced nothing, so the intent stays retryable. From approval onward an intent is permanent, because reports, proposals, and epics point back at it; only drafts can be discarded.
## Standing intents
An intent's triggers are what make the outer loop continuous. An intent with no triggers fires once on approval and concludes; an intent with triggers re-arms after each run:
| Trigger | Fires when |
| --- | --- |
| Manual | You (or an agent) run Fire |
| Schedule | A cron occurrence arrives (UTC) |
| Post-merge | An epic merges in one of the scoped repositories |
| Score drop | A score crosses a threshold you set — relative drop, absolute floor, or both |
Triggers arriving while a run is already active coalesce into a single follow-up run rather than queueing in parallel — three merges during one run yield exactly one re-fire, which analyzes the repository's latest state anyway.
## Run history you can trust
Every firing produces an immutable run record: what fired it (the exact trigger provenance — which merge, which score movement, which person), a snapshot of the scope at fire time, per-analyzer outcomes, timings, and cost. History renders from the snapshot, never live scope — renaming an analyzer later cannot falsify what run 3 actually analyzed.
## Seeded intents
Finished work seeds the next aim. Review learnings, report findings, and triaged signals all create **draft intents carrying seed provenance** — "Seeded from EPC-12 review learnings", "Seeded from SIG-238" — which enter the normal approval gate like any other intent. This is the loop's closure: the output of one turn becomes the input of the next.
## Working with intents
| Action | Web | CLI |
| --- | --- | --- |
| Create | Intents → New intent | `stella intent create [--submit]` |
| Submit / approve | intent actions | `stella intent submit\|approve ` |
| Fire | Fire action | `stella intent fire ` |
| Stop the active run | Stop run | `stella intent stop-run ` |
| Run history | Analysis tab → run picker | `stella intent runs ` |
| Conclude | Conclude action | `stella intent conclude ` |
The intent view shows the live analyzer rows for the selected run, the proposals it produced, and the full activity trail.
---
# Analysis
Core concepts · https://stellaloop.com/docs/analysis/
Analysis is the heart of the system: analyzers examine your codebase and produce reports with findings and 0–100 scores, making "pull toward the North Star" measurable. Two properties define it: a **uniform analyzer interface** (agentic and deterministic analyzers are indistinguishable to everything downstream) and **comparability by construction** (every score permanently records the analyzer version, rubric version, and model that produced it).
## Analyzers
An analyzer is a unit of analysis described by one manifest: what it targets (repositories, paths, North Star document types), whether it scores and against which areas, what model tier it requests, and how it executes.
- **Agentic analyzers** run as hosted agent sessions with read-only access to your repositories at an exact commit: a UX walkthrough agent uses the product like a user; a security reviewer reads the diff surface. Their rubric ships with calibration anchors so scoring stays grounded.
- **Deterministic analyzers** run a command in a sandbox and parse its output — static analysis, metrics, checks — with structured output formats supported out of the box.
Three ways to author one, all producing the same artifact:
1. **Repo config** — check manifest files into `.stella/analyzers/` in a linked repository; they sync automatically, and content changes require a version bump.
2. **In-app builder** — a guided wizard, including rubric authoring.
3. **Registry** — browse the shared registry and install into your project, pinned to a version. The built-in suite ships here: UX walkthrough, code quality, security review, feature pre-scoping, gap analysis, demand signals, and North Star satisfaction.
## Runs
Analyzer runs fan out in parallel (with a per-project concurrency limit and visible queue positions) and stream progress live. Cancellation is cooperative and immediate to request; transient failures retry with backoff; parse and validation failures never auto-retry — they are bugs to fix, and the error tells you what happened. Every run records its cost.
## Reports
A report (`RPT-n`) is evidence, not prose: findings with severity, area, and `file:line` code references; per-area scores; references to the North Star documents evaluated; and a markdown body. Reports are project-level assets — reusable across proposals and epics, listed and searchable, with a "Derive proposals" action that hands the pool its input.
## Scores you can trust
Scores are integers from 0 to 100, kept honest by structure:
- Every score permanently records the **analyzer version, rubric version, and model** that produced it.
- Deltas are computed only against a **same-rubric predecessor**. Changing a rubric mints a new analyzer version and starts a new baseline — charts mark the segment break instead of drawing a misleading delta across it.
- Agentic score submissions that move a comparable score must include an **explanation**.
- A daily audit samples agentic scores and re-scores them with an independent reviewer pinned to the identical rubric; deviations beyond tolerance are flagged visibly until cleared.
- Missing data renders as absence — an em dash, never a fake zero.
Per-document scores roll into the project composite through the [constellation weights](https://stellaloop.com/docs/north-star/); per-area scores power the dashboard's "by area" view.
## The dashboard
The project home is the analysis dashboard: the composite ScoreRing with its delta, score-over-time with per-loop grouping, by-area and by-document tables with signed deltas, and a live "N agents working" indicator while runs are in flight. Everything updates in realtime — no refresh button exists.
## Working with analysis
| Action | Web | CLI |
| --- | --- | --- |
| Run analysis | Dashboard → Run analysis, or fire an intent | `stella analyzer run [slugs…] [--watch]` |
| Watch runs | live rows | `stella analyzer runs` |
| Cancel / retry | run controls | `stella analyzer cancel\|retry` |
| Read reports | Reports | `stella report list`, `stella report show RPT-n` |
| Scores | Dashboard | `stella score list [--history]` |
| Manage analyzers | Analyzers | `stella analyzer list\|show\|install\|publish` |
`stella analyzer run --watch` streams run states and exits non-zero if any run fails — convenient in scripts and CI-like flows.
---
# Proposal pool
Core concepts · https://stellaloop.com/docs/proposal-pool/
The pool is the junction between discovery and delivery. Analysis yields proposals, proposals pool and compete, and promotion out of the pool is the moment an epic is born. The pool exists because spec'ing is the expensive stage — prioritization must happen before the costly work, not after.
## Proposals and sibling sets
A proposal (`PRP-n`) is a candidate piece of work: problem, approach, trade-off note, estimated scope and impact, affected repositories. Every proposal — including ones you write by hand — is anchored to at least one source report, which is what keeps the provenance chain unbroken.
Proposals group into **sibling sets**: competing approaches to one problem. The set carries the problem statement; the proposals are the answers. Independent proposals are simply sets of one. The set is the unit the pool orders, blocks, prunes, and promotes.
Most proposals arrive automatically: when an intent's analysis settles, a derivation agent reads the reports and drafts proposals — deduplicating against what's already open, adding alternatives to existing sets rather than creating twins. Derivation is all-or-nothing: a failed run inserts nothing and stays visible and retryable.
## Ordering, dependencies, pruning
- **Priority bands** — urgent, high, medium, low — with free reordering inside each band. Ordering is entirely keyboard-accessible: Space grabs an entry, arrows move it (crossing bands re-prioritizes), Space drops; 1–4 set the band directly.
- **Dependencies** — an "after: X" edge between entries, with cycle prevention. Entries with unmet dependencies sit in the Blocked tab and flip to Ready — live — the moment the prerequisite epic completes.
- **Pruning** — declining a set requires a reason, and pruned sets are archived, not deleted; restore is one action. Nothing disappears silently.
Agents read the pool in exactly the order you see it: `stella pool show` returns the same ranking the screen renders.
## Promotion — where epics are born
Promoting a sibling set out of the pool creates the epic, atomically, and it is deliberately the only way an epic can be created — in the UI, the API, or the CLI. Promotion passes the `epic.promote` checkpoint, which requires human approval by default: this is the loop's cost-commitment point.
Two modes:
- **Prune-first** (default) — promote one chosen sibling; the epic starts with a single candidate. For sets of one this is implicit.
- **Tournament** — promote the whole set into one epic with one candidate per sibling, each implemented on its own branch, with review selecting the winner on results. See [Epics and tasks](https://stellaloop.com/docs/epics-and-tasks/).
The promote dialog shows the engine's **promotion guidance**: a recommendation (prune or tournament) with its rationale and per-mode cost estimates, computed from three signals — how divergent the approaches are, how high the stakes, and whether the budget has headroom. A tournament is recommended only when all three hold.
Promotion outcomes are structured everywhere: created, held for approval, denied with a reason, blocked on named unmet dependencies, or conflicted (someone promoted it first). The CLI exits non-zero on blocked and names every unmet prerequisite.
## Working with the pool
| Action | Web | CLI |
| --- | --- | --- |
| View the pool | Pool (Ready / Blocked / Archived tabs) | `stella pool show [--tab …]` |
| Submit a proposal | New proposal (report required) | `stella proposal submit --report RPT-n …` |
| Reorder | drag or keyboard | `stella pool reorder --after ` |
| Set priority | 1–4 | `stella pool prioritize high` |
| Dependencies | D | `stella pool depend --after ` |
| Prune / restore | X | `stella proposal prune\|restore ` |
| Promote | P | `stella proposal promote [--tournament]` |
---
# Epics and tasks
Core concepts · https://stellaloop.com/docs/epics-and-tasks/
The epic is the container of the delivery half of the loop; the task is its implementable unit. An epic is born only at [promotion](https://stellaloop.com/docs/proposal-pool/) — the commitment point — and arrives carrying its full provenance: signal, intent, report, proposal.
## The epic pipeline
```
Plan → Implement → Review → Done (+ Cancelled from any stage)
▲ │
└─── fix ────┘ re-spec ──► Plan
```
The pipeline is an explicit state machine enforced server-side — an epic's stage is never a status field someone forgot to update. Loop-backs are counted and recorded, so "this epic took two fix cycles" is a fact you can read, not a memory.
Stage advancement is trailing-edge: a stage completes when no active candidate still has work in it, while individual candidates run ahead — in a tournament, candidate a can be implementing while candidate b is already in review.
## Candidates and tournaments
Every epic has at least one **candidate** — an approach with its own spec and its own branch. A tournament epic (promoted from a full sibling set) has several, racing:
- Each candidate gets a branch named `epic/EPC-n/candidate-` — created in **every** repository in the epic's scope, because epics are multi-repo capable and a candidate's work merges as one coordinated change set.
- Candidates move `specing → implementing → in review`, ending `won`, `lost`, or `withdrawn`.
- Review selects the winner on evidence — findings, fix cycles, checks, score impact, cost — and the losing candidates are archived with **structured learnings**: what was tried, why it lost, insights worth keeping. Learnings can seed future intents.
Cancelling an epic or withdrawing a candidate also requires learnings. Abandoned work teaches; it never just vanishes.
## Tasks
Tasks (`TSK-n`) arrive in bulk from [Plan's decomposition](https://stellaloop.com/docs/plan/), each belonging to exactly one candidate and one repository. The task machine:
```
todo → claimed → in progress → in review → done
(blocked ⇄) (reopened for fix directives)
```
A task is **ready** when it's unclaimed and every dependency is done — `stella work list --ready` is the one query an idle agent needs.
### Race-safe claiming
Claiming is built for agent contention:
- **Compare-and-swap** — a claim presents the state it read; a stale read loses cleanly with `already_claimed` rather than an error storm.
- **Fencing** — every claim gets a monotonic version, and claim-scoped writes must present it. An agent that crashed, lost its claim, and came back cannot corrupt the task's state.
- **Leases** — claims carry a lease (15 minutes by default) renewed by heartbeats. If an agent dies, the lease expires and the task returns to the ready pool automatically.
Humans assign themselves without leases; humans can release a stuck claim, agents cannot force-unclaim each other.
### Sessions and context
A work session records the runner, the resolved model tier, an append-only event timeline (status updates, log lines, commit references, the result), and cost. Before writing code, an implementer reads the full picture in one command:
```
stella context show TSK-214
```
The context bundle includes the task, the repository, the candidate and its spec, the epic, the provenance chain, the relevant North Star documents, related reports, comments, and the caller's claim — nobody starts by reconstructing what the team already knows.
## Working with epics and tasks
| Action | Web | CLI |
| --- | --- | --- |
| Epic list / view | Epics | `stella epic list`, `stella epic show EPC-n` |
| Stage history | epic view | `stella epic stages EPC-n` |
| Cancel / withdraw | epic actions (learnings required) | `stella epic cancel`, `stella epic withdraw-candidate` |
| Ready work | Tasks | `stella work list --ready` |
| Claim / unclaim | task actions | `stella task claim\|unclaim TSK-n` |
| Update status | board or task view | `stella status update TSK-n --state done` |
| Full context | task view | `stella context show TSK-n` |
The task surface offers a state-grouped list and a drag-validated board, saved views, bulk actions, and a complete keyboard map. There is deliberately no "New epic" button anywhere.
---
# Plan
Core concepts · https://stellaloop.com/docs/plan/
Plan is the first stage of an epic: it turns each candidate into a reviewed, approved specification and decomposes that specification into the tasks the Implement stage executes. Its guarantee is that no delivery work starts from an unvetted plan — exactly one spec exists per candidate, approval is an explicit gated act, and decomposition hands off a validated task set.
Plan is where two product opinions become concrete: the spec tool is pluggable behind an adapter, and the loop's most expensive model spend is deliberate — spec authoring runs at the frontier tier by default.
## Spec tools
Every spec tool is driven through one adapter interface. Two ship:
- **OpenSpec** (default) — the reference implementation. Specs live as OpenSpec changes in the candidate's working tree, task lists parse natively, and when a candidate merges, its spec deltas fold into the repository's established specs.
- **Generic markdown** — for teams with bespoke document conventions: configure the artifact paths, validate with an agent-backed rubric, and use the generic decomposition step.
The adapter is chosen per project and pinned onto each spec at creation, so changing project configuration never retargets work in flight.
## Authoring and revisions
Spec content lives on the candidate branch — the branch is the source of truth. The app keeps rendered snapshots for the viewer, the API, and the CLI, flags drift when the branch moves ahead ("Sync now" rather than silently stale), and re-syncs before any approval so nobody approves an outdated snapshot.
Authoring runs as a hosted agent session at the frontier tier, with the full provenance context injected: the proposal, its source report, the intent, and the relevant North Star documents. Validation failures loop back to authoring with structured issues attached.
Revisions are first-class:
- **Request changes** during review of the spec loops back to authoring as a new revision.
- **Re-spec** — when [review](https://stellaloop.com/docs/review/) escalates past a fix — reopens the spec as revision n+1 with the review findings attached as context. Prior revisions stay immutable, and per-artifact diffs between any two revisions remain available even after branches are deleted.
## Approval
Approving a spec is a checkpoint (`spec.approve`) — approve-by-default out of the box, meaning it auto-approves after an objection window unless someone objects, and configurable like every gate. Approval re-validates first, then hands the candidate to decomposition.
## Decomposition and handoff
The approved spec is decomposed into a task draft — natively by the spec tool where it can, otherwise by a generic decomposition session. Drafts are validated before anything is created: dependencies must form a cycle-free graph, every task must map to exactly one linked repository, and estimated tiers must be real tiers. Multi-repo epics add a human confirmation step before handoff by default.
The handoff materializes the tasks (`TSK-n`), records which spec revision produced them, and happens at most once per revision — a re-spec's new handoff reconciles the prior revision's tasks rather than duplicating them.
## Working with Plan
| Action | Web | CLI |
| --- | --- | --- |
| Read the spec | epic → Plan tab | `stella spec show [--artifact …]` |
| Revision diff | revision timeline | `stella spec show --diff 2..3` |
| Approve | Review bar | `stella spec approve ` |
| Request changes | Review bar | `stella spec request-changes --notes "…"` |
| Decompose / retry | Decomposition panel | `stella spec decompose [--retry]` |
| Stage status | epic view | `stella spec status EPC-n [--watch]` |
| Configure the spec tool | project settings | `stella spec config show\|set` |
---
# Review
Core concepts · https://stellaloop.com/docs/review/
Review is where the loop earns its name. Every candidate that finishes implementation gets an evaluation round by a configurable panel; findings synthesize into an auditable recommendation; and the decision drives one of three modeled edges — fix, re-spec, or accept. Review also selects tournament winners, drives the merge, and mines finished work for the learnings that start the next loop.
## Panels and lenses
A review round is evaluated by a panel. The default panel is four reviewer agents, each with an explicit lens:
| Lens | Question | Blocking |
| --- | --- | --- |
| Correctness | Does the change do what the spec says, without regressions | Yes |
| Security | Vulnerabilities, secrets, unsafe patterns | Yes |
| Spec fidelity | Does the implementation match the candidate's spec (scored 0–100) | Yes |
| North Star | Alignment with the project's constellation | Advisory |
A design-system lens is available for projects with UI surface, and you can add human members — a specific person or a role. Panel composition is snapshotted when a round starts, so config edits never mutate reviews in flight.
Reviewer sessions run read-only — exact candidate-commit mounts, no write or shell access, one structured finding-submission tool — and each receives the North Star documents relevant to its lens plus the candidate's spec and provenance, so findings are grounded in your project's own doctrine rather than reviewer taste. Iteration n+1 receives all prior findings, so it verifies fixes instead of rediscovering them.
## Findings and the recommendation
Findings carry severity (blocker, major, minor, info), a kind, code references with commit SHAs, and a suggested action. When the panel completes, duplicates are clustered and deterministic rules produce the recommendation:
1. Any open re-spec finding of major severity or above → **re-spec**.
2. Otherwise any open blocker, or a major fix from a blocking lens → **fix**.
3. Otherwise → **accept**, held until the change set's checks are green.
Agents propose; rules decide; humans confirm per your checkpoint policy.
## The three edges
- **Fix** issues a fix directive — a tracked document that reopens the named tasks (or creates new ones) and reports back when the work completes. `REVIEW_FIX` returns the candidate to Implement; round n+1 verifies.
- **Re-spec** escalates past a fix: the candidate's spec reopens as a new revision with the findings attached as context. See [Plan](https://stellaloop.com/docs/plan/).
- **Accept** moves toward merge, through the `review.signoff` gate and then the `epic.merge` gate — the irreversibility point, which requires human approval by default.
Every decision routes through the same checkpoints whether it comes from the UI, the CLI, or the API.
## GitHub, both directions
Findings with code references can post as pull-request review comments, and PR reviews written on GitHub flow back in as findings — "Request changes" on GitHub is honored as a major fix suggestion. Check runs project onto the review live, and accept is gated on green checks by default.
## Tournament selection
When the last candidate of a tournament becomes selection-ready, a selection round starts with a comparison matrix per candidate: open and resolved findings by severity, fix cycles, checks state, score impact, spec fidelity, and cost. A selection reviewer produces a ranking with rationale; the decision is sign-off gated; the winner proceeds to merge and the losers are archived with structured learnings.
## Merge
Review is the sole initiator of merges. A merge run verifies preflight (checks green, PRs mergeable and current, approvals present, gate satisfied), then merges the winning candidate's branch-set in dependency order across every repository in scope. Cross-repo merges are ordered, not atomic — and the product says so honestly: a failure halts at position k with the reason recorded, and recovery is resume (continue from k) or a commanded rollback that opens revert PRs for the already-merged members.
## Closing the loop
Merge completion records a completion learning and drafts **seed intents** from accumulated learnings and unresolved observations. Promote a seed and it becomes a real [intent](https://stellaloop.com/docs/intents/) carrying its provenance; dismiss the ones that don't warrant a loop. Resolution notices answer the [signals](https://stellaloop.com/docs/signals/) that motivated the work. The loop begins again.
## Working with review
| Action | Web | CLI |
| --- | --- | --- |
| Round status | epic → Review tab | `stella review status EPC-n` |
| Findings | findings list | `stella review findings ` |
| Submit a finding | — (panel/GitHub/human) | `stella review submit-finding --review ` |
| Decide | Outcome bar | `stella review decide ` |
| Selection | Selection panel | `stella review selection EPC-n` |
| Merge status / queue | Merge card | `stella review merge-status\|merge EPC-n` |
| Learnings and seeds | Learnings panel | `stella review learnings`, `stella review seeds` |
---
# The loop engine
Core concepts · https://stellaloop.com/docs/loop-engine/
The loop engine is what makes the stages one governed loop rather than a line of features. It owns four things: the project-level loop object and its numbered iterations, the canonical stage-transition table every surface enforces, checkpoint policy, and model economics. Its guarantee: every transition is validated against one law, every gate evaluation is audited — including autonomous pass-throughs — and budget stops are visible stops, never silent downgrades.
## The loop object and iterations
Each project has one loop with an iteration counter — the header reads "Loop 12 · running · 3 agents". An iteration opens when an intent activates and closes when every epic promoted within it settles and its learnings have seeded. The closing summary answers "what did loop 12 do": score delta, epics shipped, learnings seeded, spend.
The loop can run in **manual** or **continuous** mode. In continuous mode, merge and iteration-closed events are exactly the triggers [standing intents](https://stellaloop.com/docs/intents/) subscribe to — the loop turns itself. Pause blocks autonomous pass-throughs and new work while in-flight work finishes; approvals decided while paused apply on resume.
## One transition table
The permitted stage edges — seven forward, five loop-backs — live in one versioned table. Client state machines derive from it and server mutations validate against it, so an illegal transition is rejected and audited no matter which surface attempted it. Attribution is by provenance, not wall clock: a work unit belongs to the iteration of its owning chain, even when iterations overlap.
## Checkpoints and the autonomy dial
Every consequential transition passes a named gate:
| Gate | Guards | Default |
| --- | --- | --- |
| `intent.activate` | An intent starting analysis | Autonomous |
| `proposal.derive`, `pool.enter` | Proposal derivation and pooling | Autonomous |
| `epic.promote` | The commitment point — an epic being born | **Requires approval** |
| `spec.approve` | A candidate's spec | Approve by default |
| `review.request`, `review.signoff` | Entering review; accepting the verdict | Autonomous; approve by default |
| `epic.merge` | The irreversibility point | **Requires approval** |
| `loopback.fix`, `loopback.respec` | The return edges | Autonomous |
| `intent.seed` | Learnings seeding the next intent | Autonomous |
| `signal.triage`, `signal.respond` | Agent-applied triage; outward resolution notices | Governed independently |
Three modes per gate:
- **Require approval** — the transition holds until a person (or an explicitly authorized agent) decides.
- **Approve by default** — an approval is created with a deadline (30 minutes by default); it auto-approves unless someone objects first, which converts it to blocking.
- **Autonomous** — passes through, still audited.
The **autonomy dial** — supervised, balanced, autonomous — sets every gate at once; any per-gate override moves the project to custom. Approvals are actionable everywhere: inline in the [inbox](https://stellaloop.com/docs/notifications/), from the desktop notification, or `stella approve `. The requester can never decide their own approval, and agents decide only where you have explicitly listed them.
## Model tiers
Stages request a tier — **frontier**, **standard**, or **economy** — and the engine resolves the concrete model from your project's configuration. Defaults: Plan runs frontier, Analyse/Propose/Implement run standard, Review runs a panel of three. Per-work-unit overrides exist for the cases that warrant them, and a missing model mapping is an error, never a silent substitution.
Every model-backed piece of work — analyzer runs, derivation, spec sessions, task sessions, review panelists — registers as a work unit, which is what powers the live "N agents working" count and per-run cost capture.
## Budgets and costs
Budgets exist at three grains — per project period, per loop iteration, and per epic tournament — each with a warn threshold and a hard stop:
- Admission is checked when work starts; a hard-stopped budget denies **new** work while in-flight work finishes and records its cost.
- A tournament hitting its budget stops with best-so-far selection through the normal review gates.
- Cost is truthful: prices are snapshotted at admission, usage settles idempotently, and unpriced work is labeled unknown — never presented as $0.
Ask "what did loop 12 cost?" and the answer is a number: `stella costs show`.
## Working with the engine
| Action | Web | CLI |
| --- | --- | --- |
| Loop status / history | header widget · settings → Loop | `stella loop status`, `stella loop history` |
| Pause / resume / mode | settings → Loop | `stella loop pause\|resume\|mode` |
| Approvals | settings → Approvals · inbox | `stella approvals list`, `stella approve\|reject\|object ` |
| Gates and the dial | settings → Gates & autonomy | `stella gates list\|set\|dial` |
| Tiers | settings → Tiers | `stella tiers show\|set` |
| Budgets and costs | settings → Budgets | `stella budgets show\|set`, `stella costs show` |
| Promotion guidance | promote dialog | `stella guidance promotion ` |
---
# Provenance
Core concepts · https://stellaloop.com/docs/provenance/
Every piece of committed work in Stella Loop carries an immutable chain of references back to what motivated it. When someone asks "why are we building this?", the answer is a chain of records, not an archaeology project.
## The chain
```
epic → proposal → report → intent [→ signal → external source]
```
- The **intent** records what fired it — a trigger event, a seed from prior learnings, a person, or a signal.
- Every analyzer run and **report** records its intent and run.
- Every **proposal** records its source report(s). Provenance is mandatory and immutable — even hand-written proposals anchor to a report.
- **Promotion** passes the full chain into the epic, where it is surfaced on every view.
- **Tasks** extend it further: task → spec revision → candidate → epic.
- **Signals** extend it end to end: a support ticket is traceable to the merged change that resolved it — and the loop can answer back with a resolution notice.
A worked example, navigable in both directions:
```
SIG-238 → INT-31 → RPT-41 → PRP-19 → EPC-12 → TSK-214
```
A Slack message seeded an intent; the intent's UX walkthrough produced a report; the report yielded a proposal; the proposal was promoted into an epic; the epic decomposed into tasks. Six records, one question answered.
## Display IDs
Every entity kind carries a human-readable sequence ID, used consistently across the UI, the CLI, the API, and even pull-request titles:
| Prefix | Entity | Scope |
| --- | --- | --- |
| `SIG-n` | Signal | Organization |
| `INT-n` | Intent | Project |
| `RPT-n` | Report | Project |
| `PRP-n` | Proposal | Project |
| `EPC-n` | Epic | Project |
| `TSK-n` | Task | Project |
Display IDs are first-class addresses: `stella epic show EPC-12` and `GET /api/v1/projects/{p}/epics/EPC-12` resolve them directly, global search jumps to them exactly, and Stella-managed pull requests are titled `[EPC-12] …` with a provenance block in the body linking back.
## Why it matters
- **Decisions stay justified.** Promotion approvals show the evidence chain, so the person holding the gate sees why the work exists before spending on it.
- **Agents get real context.** `stella context show TSK-214` walks the chain to assemble the intent, the North Star lines, the spec, and the reports — the same context a senior teammate would give.
- **Feedback closes.** Because the chain reaches the original signal, shipping the fix can notify the person who reported the problem — automatically, once, with a privacy-safe message.
- **History cannot be falsified.** References are immutable, run history renders from point-in-time snapshots, and renames or deletions cannot rewrite what actually happened.
---
# Agents
Agents · https://stellaloop.com/docs/agents/
Agents are first-class users of Stella Loop, not an integration. Every capability a human has in the UI is available through three agent surfaces — the `stella` [CLI](https://stellaloop.com/docs/cli/), the public [`/api/v1` API](https://stellaloop.com/docs/api/), and a generated [MCP server](https://stellaloop.com/docs/mcp/) — and that parity is an enforced artifact, not a policy: one capability map generates the API routes, the OpenAPI document, the CLI command tree, and the MCP tool set, and continuous integration fails when any surface is missing a capability.
Practically, that means an agent never hits a wall where "you have to do that in the app". Creating intents, deriving proposals, promoting (through the same gates), claiming tasks, submitting reports and findings, approving checkpoints it is authorized to approve — all of it is scriptable.
## Identity and API keys
Agents authenticate with API keys — first-party credentials bound to an actor in your organization:
- Format `slk_…`; the secret is shown exactly once at creation, and stored hashed.
- **Scopes** — `read`, `work`, `admin` — bound the key's power, and **project grants** limit which projects it reaches. Effective permission is the key's scopes intersected with its actor's permissions: a key can never grant more than its actor has.
- Keys support rotation with a grace window, immediate revocation, and expiry.
Create keys in settings → **API keys**. Every request an agent makes is attributed to the key's actor — the activity log reads "cc-03 claimed TSK-214", not "the API did something".
## The canonical agent session
The self-discovering session every coding agent can run:
```
printf %s "$STELLA_API_KEY" | stella auth login --with-key
stella project switch ATLAS
stella work list --ready # what can I do right now?
stella task claim TSK-214 # race-safe claim with a lease
stella context show TSK-214 # intent · spec · North Star · reports
# … implement on the candidate branch …
stella status update TSK-214 --state done
stella events tail --follow # wake on new work instead of polling
```
Every step is equally available as a raw endpoint (`stella api GET /projects/ATLAS/tasks`) and as an MCP tool (`stella_task_claim`).
## Being told, not polling
Two mechanisms keep agents event-driven:
- **Event feed** — `GET /api/v1/…/events` with long-polling, or the server-sent-events stream behind `stella events tail --follow`, with lossless resume.
- **Webhooks** — HMAC-signed deliveries to your endpoint with retries and dead-lettering. An agent actor whose notification preferences enable the webhook channel is woken when a task is assigned to it — `task.assigned` arrives, the agent claims, no `work list` loop required.
## Governance applies to agents too
Agents work under the same rules humans do:
- Checkpoint gates hold agent-initiated transitions exactly as they hold human ones; agents can decide approvals only where they are explicitly listed as approvers.
- Claiming is fenced and leased, so a crashed agent's task returns to the pool and a zombie process cannot corrupt state.
- Rate limits and idempotency keys make retry loops safe; the API's error taxonomy maps to stable CLI exit codes so scripts can branch on outcomes.
## Reading these docs as an agent
This site is agent-readable by design: [/llms.txt](https://stellaloop.com/llms.txt) is the quick orientation — one page that says what Stella Loop is and links everywhere — and [/llms-full.txt](https://stellaloop.com/llms-full.txt) collates the complete documentation into a single file.
## Hosted agents
Beyond agents you run yourself, Stella Loop runs its own hosted agent sessions for analysis, spec authoring, implementation tasks, and review panels — on a managed runtime with read-only repository mounts at exact commits, least-privilege credentials, deny-by-default tools, and a bounded trusted-commit contract for landing changes. You choose the model tiers and budgets; see [The loop engine](https://stellaloop.com/docs/loop-engine/).
---
# CLI
Agents · https://stellaloop.com/docs/cli/
`stella` is Stella Loop's primary agent surface — a product surface in its own right, not tooling. The founding bet: every coding agent can run a shell command and read `--help`, so a first-class CLI with an excellent help system is the durable agent interface. The CLI is a strict thin client over the public [API](https://stellaloop.com/docs/api/) — there are no private endpoints behind it.
## Install and authenticate
```
npm install -g @stella-loop/cli
printf %s "$STELLA_API_KEY" | stella auth login --with-key
stella whoami
stella project switch ATLAS
```
Configuration lives in `~/.stella/config.json` (written with owner-only permissions), with per-API-URL credentials. Precedence: flags > environment (`STELLA_API_KEY`, `STELLA_API_URL`, `STELLA_PROJECT`, `STELLA_ORG`) > stored config. Self-hosted deployments point `--api-url` (or `STELLA_API_URL`) at their own origin.
## Help is a contract
An agent must be able to operate the product from `--help` alone — and that is tested, not hoped:
- Every command documents a synopsis, examples, and related commands; root help ships a "Typical agent session" walkthrough and the exit-code table.
- Unknown commands get nearest-command suggestions.
- Group help for `epic`, `proposal`, and `spec` includes the rules that matter — for example, every proposal requires at least one `--report` at creation.
## Contracts every command obeys
- **`--json`** — exactly one stable JSON document on stdout; errors as JSON on stderr. In agent mode (`--json` or a non-TTY), prompts, colors, and spinners are disabled, and destructive operations require `--yes` or fail with `confirmation_required`.
- **Exit codes** — `0` ok · `1` runtime · `2` usage · `3` auth · `4` permission · `5` not found · `6` conflict · `7` rate limit · `8` validation. A losing claim race is exit 6, distinguishable from a crash.
- **Transport** — automatic idempotency keys on mutations, bounded retries on transient failures honoring `Retry-After`, and an upgrade notice when the server requires a newer client.
- **Watching** — `stella events tail --follow` and `stella activity tail --follow` stream server-sent events with resume and duplicate suppression.
## The command tree
Generated from the same capability map as the API, so it is always complete. The main groups:
| Group | What it covers |
| --- | --- |
| `stella signal` / `stella capture` | Capture, list, triage, connectors, demand corpus |
| `stella northstar` | Documents, versions, diffs, weights, tensions, repo sync |
| `stella intent` | Create, submit, approve, fire, runs, conclude |
| `stella analyzer` / `report` / `score` | Registry, runs, reports, scores |
| `stella proposal` / `pool` | Submit, promote, prune, reorder, dependencies |
| `stella epic` | List, show, stages, cancel, withdraw-candidate |
| `stella work` / `task` / `context` / `status` / `session` | Ready work, claiming, context bundles, status updates, work sessions |
| `stella spec` | Specs, revisions, approval, decomposition |
| `stella review` | Rounds, findings, decisions, selection, merge, learnings, seeds |
| `stella loop` / `approvals` / `approve` / `reject` / `gates` / `tiers` / `budgets` / `costs` | The loop engine surface |
| `stella inbox` / `watch` / `notify` | Notifications, watching, preferences |
| `stella repo` / `changeset` | Repositories, change sets, merges |
| `stella key` / `webhook` / `events` / `search` / `api` | Keys, webhooks, the event feed, global search, and the raw escape hatch |
`stella api ` is the day-zero escape hatch for any endpoint, and `stella completion ` generates shell completions.
## MCP server
The same binary serves MCP: `stella mcp serve` (stdio, or `--transport http`). See [MCP](https://stellaloop.com/docs/mcp/).
---
# API
Agents · https://stellaloop.com/docs/api/
Everything in Stella Loop is reachable through `/api/v1` — the [CLI](https://stellaloop.com/docs/cli/) and the [MCP server](https://stellaloop.com/docs/mcp/) are thin clients over it, and there are no private endpoints behind either. The API is self-describing: an unauthenticated `GET /api/v1` returns discovery information, and the complete OpenAPI 3.1 document is served at `GET /api/v1/openapi.json`.
## Authentication
Send an API key as a bearer token:
```
curl -H "Authorization: Bearer $STELLA_API_KEY" \
https:///api/v1/projects/ATLAS/tasks
```
Keys carry scopes (`read` < `work` < `admin`) and project grants; requests outside them return `permission_denied` with the missing requirement named. Every request is attributed to the key's actor. Keys are created, rotated (with a grace window), and revoked in settings → **API keys** — the secret is shown once.
## One envelope
Success responses share one shape, errors another:
```json
{ "data": { … }, "requestId": "req_…", "pageInfo": { "cursor": "…" } }
{ "error": { "code": "task_already_claimed", "message": "…" }, "requestId": "req_…" }
```
- Every response carries a request ID for support and correlation.
- Collections paginate by cursor.
- Error codes are a stable, machine-readable taxonomy shared with the CLI's exit codes — `unauthenticated`, `permission_denied`, `not_found`, domain conflicts like `task_already_claimed` (409), `rate_limited` (429 with `Retry-After`), `validation_failed`.
## Display-ID addressing
Human-readable IDs are first-class addresses. These are equivalent:
```
GET /api/v1/projects/ATLAS/epics/EPC-12
stella epic show EPC-12
```
`SIG-n`, `INT-n`, `RPT-n`, `PRP-n`, `EPC-n`, and `TSK-n` resolve everywhere an ID is accepted.
## Idempotency and rate limits
- Mutating requests accept an `Idempotency-Key` header; replays return the recorded response with an `Idempotent-Replay` header, so retry loops are safe. The CLI sends one automatically.
- Rate limits are classed (read / write / expensive) with burst allowances; `429` responses carry `Retry-After` and rate-limit headers.
## Events out
Two ways to be told instead of polling:
- **Event feed** — `GET …/events` with cursor pagination, type filters, and a `wait=` long-poll hold; or `GET …/events/stream` for server-sent events with heartbeats and `Last-Event-ID` lossless resume.
- **Webhooks** — register HTTPS destinations, receive HMAC-signed deliveries (`X-Stella-Signature` over `timestamp.body`), verify, and process. Deliveries retry with backoff and dead-letter after repeated failure; a synchronous test ping exists for setup. Webhooks can also serve as an agent actor's notification channel — `task.assigned` wakes the agent that should claim.
## Gates apply here too
The API enforces exactly what the UI enforces: promotion passes the `epic.promote` checkpoint, merges pass `epic.merge`, invalid stage transitions are rejected with the legal edges named, and approval decisions respect approver policy. A held transition returns its approval reference so your automation can wait for the decision — or surface it to a human.
---
# MCP
Agents · https://stellaloop.com/docs/mcp/
Stella Loop ships a Model Context Protocol server so MCP-speaking agents — Claude Code and others — can drive the product as native tools. The server is generated from the same capability map as the [API](https://stellaloop.com/docs/api/) and [CLI](https://stellaloop.com/docs/cli/), so its tool set cannot drift from what the product can actually do.
## Running the server
The MCP server is part of the CLI:
```
stella mcp serve # stdio (the common case)
stella mcp serve --transport http --port 3333 # streamable HTTP at /mcp
```
A typical client configuration:
```json
{
"mcpServers": {
"stella": {
"command": "stella",
"args": ["mcp", "serve"],
"env": { "STELLA_API_KEY": "slk_…", "STELLA_PROJECT": "ATLAS" }
}
}
}
```
The server can start before credentials exist — a tool call without a key returns a structured error naming the fix, which suits ephemeral agents that receive their key after boot. Over HTTP, each request gets a fresh, stateless server instance, so multiple coding agents can share one endpoint without leaking state between them.
## The tools
Tools are named `stella__` — `stella_work_list`, `stella_task_claim`, `stella_context_show`, `stella_signal_capture`, `stella_proposal_promote`, and so on across the full surface: signals, North Star, intents, analysis, the pool, epics and tasks, specs, review, the loop engine, notifications, repositories, and search.
Each tool carries annotations derived from its scope and method — read-only, destructive, idempotent — so agent frameworks can apply their own confirmation policies sensibly. Inputs and outputs follow the same schemas as the API envelope.
## The same rules apply
MCP tools hit the same `/api/v1` endpoints with the same key, so scopes, project grants, rate limits, idempotency, and checkpoint gates all behave identically. An MCP agent promoting a proposal still passes `epic.promote`; a claim race still loses cleanly with a structured conflict.
If a capability seems missing from your client's tool list, update the CLI — the tool set versions with it.
---
# Web app
Platform · https://stellaloop.com/docs/web-app/
The web app at [app.stellaloop.com](https://app.stellaloop.com) is a dense, keyboard-first interface in the Linear family: fast navigation, a command palette from day one, and realtime everywhere. It is designed for desktop-class screens (it degrades gracefully to about 900 pixels wide; there is no phone layout), and it ships dark — a light theme is architecture-ready but not yet designed.
## Realtime by default
Everything you watch is a live subscription: running loops, working agents, moving scores, arriving signals. There are no refresh buttons and no polling — if something changed, your screen already shows it. Liveness has a visual grammar: the aurora pulse appears only on work that is genuinely running right now, and stops the instant it settles.
## The command palette
⌘K opens the palette; every action in the product registers there, ranked by your context and recent activity. Actions unavailable in the current context say why. The palette is also the fastest navigation: type an entity name or a display ID and jump.
## Global search
/ opens search across intents, epics, tasks, proposals, reports, North Star documents, and signals. Typed filters narrow precisely:
```
type:task status:in_progress epic:EPC-12
score<50
TSK-214
```
An exact display ID jumps straight to the entity. Search is transactionally indexed — results are never stale relative to committed data — and agents get the same capability via `stella search`.
## Keyboard system
Every action is reachable without a mouse. The global map:
| Key | Action |
| --- | --- |
| ⌘K | Command palette |
| / | Global search |
| g then a letter | Go-to navigation chords |
| j / k | Traverse any list |
| ⌘⇧S | Capture a signal from anywhere |
| ? | Shortcut help overlay |
Surfaces add their own layers — the pool's grab-and-move reorder, the triage queue's single-key dispositions, the constellation's editor bindings — and bindings are customizable per person in settings, syncing across your sessions.
## Chrome that carries state
The sidebar shows live counts per surface (pending signals, ready tasks, running analysis); the header carries the loop status — "Loop 12 · running · 3 agents" — your pending approvals, and the connection state. Organization and project switching, breadcrumbs, and a first-run setup checklist round out the shell.
## Performance as a contract
The interface holds itself to budgets that are enforced in the product's own test suite — palette open in 50 ms, keystroke re-ranking in 16 ms, search results fast at the 95th percentile, 58 frames per second scrolling a ten-thousand-row list, realtime updates painted within 300 ms. A feature that works but feels slow is treated as not done.
---
# Desktop app
Platform · https://stellaloop.com/docs/desktop-app/
The desktop app wraps the same interface as the web with native ergonomics: a summon shortcut, tray presence, actionable notifications, deep links, and honest offline behavior. There are deliberately no desktop-exclusive product capabilities — every entry point executes the same actions available on web, API, and CLI.
The current release train ships for **macOS** (one universal build for Apple silicon and Intel, signed and notarized). Windows and Linux support exists in source and is exercised in tests, but packaged distribution is deferred — no availability is claimed until it is real.
## Native capabilities
- **Global summon** — ⌥Space from anywhere brings Stella Loop forward with the command palette open. The binding is rebindable, and registration conflicts are surfaced rather than silently ignored.
- **Tray / menu bar** — a status glyph reflects the loop live (idle, running, needs attention, offline) with quick actions: open, pending approvals, new intent, palette.
- **Native notifications** — the desktop delivery channel for the [notification fabric](https://stellaloop.com/docs/notifications/), actionable where the platform allows: approve a checkpoint from the notification itself. Click-through deep-links to the exact surface; notifications are suppressed while you're already looking at the app.
- **Deep links** — `stella-loop://` URLs mirror web routes one-to-one, and the web origin offers an "Open in app" handoff.
- **Dock badge** — your unread count, cleared at zero and suppressed offline.
- **Launch at login** — opt-in, off by default.
## Offline, honestly
Offline behavior favors truth over convenience:
- A cold start while offline restores your last route and a bounded, identity-scoped snapshot of your epics under a timestamped **read-only banner** — history labeled as history.
- If your identity cannot be verified offline, data stays locked rather than guessed at.
- Mutations are fenced while disconnected: no hidden queue of writes that replays surprises when you reconnect. Reconnection is automatic, and the read-only fence lifts the moment a verified connection returns.
## Updates
Updates download quietly and apply on restart — one toast when ready, a menu item that flips to "Restart to update", and no re-nagging. Releases roll out in stages, so a bad build can be halted before it reaches everyone; stable and beta channels are selectable per machine.
---
# GitHub integration
Platform · https://stellaloop.com/docs/github-integration/
Stella Loop connects to GitHub through a GitHub App with least-privilege permissions. A project links one or more repositories; branches, pull requests, checks, and reviews mirror into the product in realtime; and the delivery half of the loop lands on real branches with coordinated merges.
## Setup
1. In organization settings → **GitHub**, install the Stella Loop GitHub App on the account that owns your repositories.
2. In project settings → **Repositories**, link the repositories this project works on. Each repository chooses its version-control workflow at link time: **git** (default) or **Jujutsu** — jj runs colocated on git, so the GitHub side is unchanged while workspace commands speak jj's vocabulary.
3. If several projects share the app installation, map incoming GitHub issues to projects with connector rules (see [Signal connectors](https://stellaloop.com/docs/signal-connectors/)).
For multi-repo epics, set the **dependency order** between repositories in settings — it drives merge orchestration.
## Branch-sets and change sets
- When an epic candidate is created, Stella Loop creates its branch — `epic/EPC-12/candidate-a` — in **every** repository in the epic's scope. A single-repo candidate is just a branch-set of size one.
- A **change set** is the reviewable unit: one pull request per branch-set member, treated as one thing. Its state is computed, never asserted: a change set becomes `approved` only while every PR is approved, checks are green, and no review thread is unresolved — and it falls back to `in review` automatically on any regression.
- Merges execute in your declared dependency order, halting on the first failure with the position and reason recorded. Recovery is resume (continue from where it stopped) or rollback (revert PRs for the members that already merged). Cross-repo merges are ordered, not atomic — and the product says so rather than pretending.
Stella-managed pull requests carry their provenance: titles are prefixed `[EPC-n]`, and the body contains a maintained block linking the epic, candidate, implemented tasks, and sibling PRs.
## Webhooks are hints; the API is truth
Webhook deliveries are verified, deduplicated, and processed idempotently — and whenever a delivery is stale, contradictory, or truncated, Stella Loop re-fetches the truth from the GitHub API. An hourly reconciliation heals anything a webhook outage missed. Connection health is visible per repository (connected, degraded, disconnected, with the reason), and repositories with open change sets cannot be unlinked out from under their work.
## Issues become signals
Newly arriving GitHub issues and their comments flow into [signals](https://stellaloop.com/docs/signals/) automatically — deduplicated, with repository context attached. Pull-request events stay on the delivery side. There is deliberately no retroactive import of your existing issue backlog: imported tickets would bypass the discovery half of the loop.
## Security posture
The App requests the minimum: contents and pull-request write (branches, PRs, merges), checks and statuses read, metadata read. Hosted agent sessions never receive write-capable tokens — their repository mounts are read-only at exact commits, and changes land only through a validated commit boundary. Webhook signatures are verified before any parsing.
---
# Signal connectors
Platform · https://stellaloop.com/docs/signal-connectors/
Connectors turn external events into [signals](https://stellaloop.com/docs/signals/) automatically, so feedback reaches the loop from the channels where it already lives. Five kinds ship:
| Connector | What arrives | Notes |
| --- | --- | --- |
| GitHub Issues | New issues and their comments | Rides the [GitHub App](https://stellaloop.com/docs/github-integration/) — no separate webhook to configure |
| Slack | Messages from channels you bind | Captures acknowledge in-thread with the new `SIG-n` |
| Sentry | Alerts, with occurrence counts | Repeat occurrences coalesce into one signal's count instead of flooding the queue |
| Inbound email | Mail to a per-connector capture address | Sender verification decides whether the reporter is treated as verified |
| Webhook | Anything that can POST JSON | HMAC-signed; the generic door for your own systems |
Connectors are managed in organization settings → **Signal connectors** (admin-gated), with full CLI parity under `stella connector …`.
## How ingestion behaves
Every arrival passes one pipeline with predictable behavior:
- **Verified first.** Signatures are checked before anything is parsed; a failed signature is rejected with zero side effects.
- **Idempotent.** Redelivery of the same external event never creates a duplicate signal; follow-ups on a known item (new comments, new occurrences) append to its history and wake it if snoozed.
- **Routed by rules.** Project-mapping rules assign incoming signals to projects (a repository linked to exactly one project maps automatically); anything unmatched lands in the organization's unassigned bucket for triage.
- **Filtered visibly.** Noise filters (for example, bot authors) count what they exclude — filtered is a number you can see, not a silent void.
- **Rate-limited safely.** Per-connector admission protects the queue; over-limit deliveries from occurrence-bearing sources coalesce rather than disappear.
## Health and self-disable
Each connector tracks its own health. Repeated verification failures degrade it and eventually disable it — loudly, with a notification to organization admins — while high volume alone never does. Re-enabling is one explicit action. Disabled connectors reject deliveries with a structured reason, so the sending side can tell what happened.
## Identity and privacy
External reporters are mapped to real identities only through explicit, admin-attested links — never guessed from display names. Unverified reporters are rendered as unverified and are never sent outbound notices. Reporter identity fields can be redacted in place for data-subject requests without destroying the signal's history.
## Outbound replies
Connectors can optionally post [resolution notices](https://stellaloop.com/docs/signals/) back to their source — a comment on the GitHub issue, a Slack reply, an email — when the work that resolves a signal ships. Outbound is opt-in per connector and per project, the default message is privacy-safe, and each signal is answered at most once, ever.
---
# Notifications
Platform · https://stellaloop.com/docs/notifications/
The loop runs while nobody is looking — analyzers score, agents implement, reviews land — and its human checkpoints block on people who would otherwise never know they were needed. Notifications are the delivery fabric that fixes this: relevant events become per-recipient inbox items, fanned out to four channels from one model.
| Channel | For | Notes |
| --- | --- | --- |
| In-app inbox | Everyone | The record; triage state lives here |
| Desktop | Humans on the [desktop app](https://stellaloop.com/docs/desktop-app/) | Native, actionable — approve from the notification |
| Email | Humans | Immediate for approvals; a daily digest for the rest, sent at your local hour |
| Webhook | Agent actors | `task.assigned` wakes the agent that should claim — no polling |
## The inbox
The organization-wide inbox lives beside your projects, grouped by project, fully keyboard-driven: j/k traverse, Enter opens and marks read, e archives, u marks unread, s snoozes. Each item pairs the moment it happened (a snapshot of the event) with the live current state of the entity it points at. Repeats of the same event on the same entity coalesce into one unread row with an occurrence count — approvals excepted, because each approval request is individually actionable.
**Approvals are actionable inline.** An `approval.requested` item carries Approve and Reject; decisions are race-safe, and if someone else decided first you see who, not an error.
Unread counts are maintained transactionally — the badge is exact under concurrency, on the sidebar, and on the desktop dock icon.
## What gets delivered
- **Targeted** — approval requests and resolutions, task assignments, mentions, agent session failures and expired leases, connector health changes.
- **Watched** — stage advances, review findings, and tournament decisions on entities you watch. Watching happens automatically when you create, get assigned, comment, or are mentioned; mute is sticky and wins.
- **Broadcast pulse** — loop iterations completing and score drops, off by default for interrupting channels.
Approvals always deliver — a muted epic must not stall a checkpoint.
## Preferences and do-not-disturb
Preferences are a kind × channel matrix, set globally and overridable per project. Do-not-disturb (manual or scheduled, in your timezone) silences interruptions — desktop and webhooks withheld, immediate emails demoted to the digest — but never hides work: the inbox row and the badge always move.
## For agents
Agent actors use the same model with webhooks as their interruption channel. Bind a [webhook subscription](https://stellaloop.com/docs/api/) to the agent's actor, enable the channel, and assignments arrive as signed deliveries. Everything in the inbox is also scriptable: `stella inbox list --unread`, `stella inbox approve `, `stella watch add EPC-12`.
---
# Glossary
Reference · https://stellaloop.com/docs/glossary/
Canonical definitions of Stella Loop vocabulary. Domain nouns are capitalized as proper concepts in product copy (North Star, Intent, Epic, Proposal Pool, Candidate).
**Analyzer** — a unit of analysis, agentic or deterministic under one manifest, that examines the codebase and produces a report, usually with a score. Authored three ways: repo config files, an in-app builder, or the shared registry where the built-in suite ships. See [Analysis](https://stellaloop.com/docs/analysis/).
**Approval request** — the record created when a checkpoint gate holds a transition for a decision; actionable in-app, over the API, and via `stella approve `.
**Autonomy dial** — the project-level setting — supervised, balanced, autonomous — that configures every checkpoint gate at once; any per-gate override moves it to custom. See [The loop engine](https://stellaloop.com/docs/loop-engine/).
**Budget** — a spend control at one of three grains: per project period, per loop iteration, or per epic tournament; each with a warn threshold and a hard stop, with no silent tier downgrades.
**Candidate** — one competing solution inside an epic: its own spec and its own branch-set. In a tournament, candidates race to be the merged winner. See [Epics and tasks](https://stellaloop.com/docs/epics-and-tasks/).
**Change set** — the coordinated multi-repo unit for a candidate: one same-named branch and one pull request per repository in scope, reviewed as one and merged as one ordered operation. See [GitHub integration](https://stellaloop.com/docs/github-integration/).
**Checkpoint (gate)** — a policy point evaluated on a stage transition, returning proceed, hold (approval pending), or deny. Three modes: require approval, approve by default, autonomous.
**Connector** — an organization-level integration that turns external events into signals: GitHub Issues, Slack, Sentry, inbound email, and generic signed webhooks. See [Signal connectors](https://stellaloop.com/docs/signal-connectors/).
**Demand cluster** — merged duplicate signals accumulating a demand count; the weight behind "eleven people asked for this".
**Display ID** — the human-readable identifier per entity kind: `SIG-n` (org-scoped), `INT-n`, `RPT-n`, `PRP-n`, `EPC-n`, `TSK-n` (per-project). See [Provenance](https://stellaloop.com/docs/provenance/).
**Epic** — the committed unit of delivery work, created only by promotion from the pool; it owns the spec, tasks, implementation, and review, and carries the full provenance chain.
**Fix loop** — the Review → Implement loop-back: review findings send work back to implementation without reopening the spec.
**Intent** — the statement of aim that starts a loop turn; it names the aim and scopes the analyzers. Archetypes: directed and North Star-driven. See [Intents](https://stellaloop.com/docs/intents/).
**Learnings** — structured records captured when a candidate loses, an epic is cancelled or completes: what was tried, why it ended that way, insights worth keeping. Learnings can seed future intents.
**Loop iteration** — one numbered turn of the outer loop ("loop 12"), closed with a summary: score delta, epics shipped, learnings seeded, spend.
**Model tier** — the strength class a stage requests — frontier, standard, economy — resolved to a concrete model by project configuration.
**North Star constellation** — the full set of active North Star documents: the composite aim, with per-document weights feeding the composite score. See [North Star](https://stellaloop.com/docs/north-star/).
**North Star document** — a single versioned document of tenets, typed by concern (product, design, engineering, agent experience, or custom).
**Promotion** — the commitment point: moving a proposal or sibling set out of the pool, which atomically creates the epic. Modes: prune-first and tournament.
**Proposal** — a candidate piece of work derived from analysis (`PRP-n`): problem, approach, trade-offs, estimated scope and impact — always anchored to a source report.
**Proposal pool** — the prioritized queue of sibling sets, ordered by priority bands with dependencies; the junction between discovery and delivery. See [Proposal pool](https://stellaloop.com/docs/proposal-pool/).
**Provenance chain** — the mandatory immutable chain epic → proposal → report → intent, extended by signals to the external source. See [Provenance](https://stellaloop.com/docs/provenance/).
**Report** — the output of an analyzer run (`RPT-n`): findings with severity and code references, per-area scores, a markdown body. Reports are project-level, reusable assets.
**Re-spec** — the Review → Plan loop-back: findings escalate past a fix and reopen the candidate's spec as a new revision.
**Score** — a 0–100 integer quality measure at project, area, and document grain; every score permanently records the analyzer version, rubric version, and model that produced it.
**Seed intent** — a draft intent created from review learnings, findings, or a triaged signal, carrying seed provenance and entering the normal approval gate.
**Sibling set** — proposals that are alternative solutions to the same problem; independents are sets of one. The unit the pool orders, prunes, and promotes.
**Signal** — an uninterpreted observation from a person or connected system (`SIG-n`), captured with no required structure and triaged later. See [Signals](https://stellaloop.com/docs/signals/).
**Signal triage** — assigning a signal its altitude: seed a draft intent, attach as evidence, merge as duplicate, or dismiss with a reason.
**Spec** — the planned design for an epic candidate, produced by a pluggable spec tool — OpenSpec by default. See [Plan](https://stellaloop.com/docs/plan/).
**Standing intent** — an intent with re-fire triggers (manual, schedule, post-merge, score-drop) that re-arms after each run; what makes the outer loop continuous.
**Task** — an implementable unit derived from a spec (`TSK-n`), executed by agents or humans with race-safe claiming. States: todo, claimed, in progress, blocked, in review, done, reopened.
**Tension** — a first-class record that two North Star documents pull in opposite directions, with an open → acknowledged → resolved lifecycle.
**Tournament** — the promotion mode where a whole sibling set becomes one epic with one candidate per sibling, implemented in parallel, with review selecting the winner.
**Work unit** — the engine's registry entry for a running piece of model-backed work; the basis for tier resolution, cost capture, and the live "N agents working" count.
---
# FAQ and limitations
Reference · https://stellaloop.com/docs/faq/
Honesty is product behavior in Stella Loop — no silent fallbacks, no sample data presented as live, no claims ahead of reality. This page holds itself to the same bar.
## Does Stella Loop replace my issue tracker?
Yes — that is the intent. Stella Loop is the system of record for product work. It does not replace the rest of your stack: spec tools, analyzers, model providers, coding agents, and version control remain pluggable. See [the comparison](https://stellaloop.com/vs-linear/) for an honest look at where Linear-shaped trackers excel.
## Can I import my existing backlog?
No, deliberately. Bulk import from Linear, Jira, or GitHub Issues is a non-goal: imported tickets would bypass the discovery half of the loop — the analysis and evidence that make commitments justified. Newly arriving GitHub issues flow in as [signals](https://stellaloop.com/docs/signals/) from the moment you link a repository; your existing backlog stays where it is while you transition.
## Do I have to hand control to agents?
No. Out of the box the loop is gated at exactly the points that matter — promotion (where money starts being spent) and merge (the irreversibility point) require a human's approval, and spec approval and review sign-off give you an objection window. The [autonomy dial](https://stellaloop.com/docs/loop-engine/) is a dial: run fully supervised on day one, loosen per gate as trust grows.
## Can agents do everything a human can?
Yes — that parity is enforced, not promised. One capability map generates the API, the CLI, and the MCP tools, and CI fails when any surface is missing a capability. Agents still work under your gates, roles, rate limits, and budgets. See [Agents](https://stellaloop.com/docs/agents/).
## What does "quantify quality" actually mean?
Analyzers score the codebase 0–100 — overall, per area, per North Star document. Every score permanently records the analyzer version, rubric version, and model that produced it; deltas are only drawn against same-rubric predecessors; agentic scores that move a number must explain themselves, and sampled scores are audited by independent re-scoring. A score you cannot trust is decoration; these are built to be trusted. See [Analysis](https://stellaloop.com/docs/analysis/).
## What model providers and tools can I use?
Model routing is configured per stage through tiers (frontier / standard / economy) mapped to concrete models in project settings. Spec tools sit behind an adapter (OpenSpec ships as the default). Analyzers are pluggable — agentic or deterministic. Version control is git by default with Jujutsu supported per repository.
## Current limitations
Stated plainly:
- **Desktop is macOS-only for now.** Windows and Linux support exists in source and tests, but packaged, signed distribution is deferred — we do not claim availability we have not proven. Web and CLI cover every platform in the meantime.
- **Dark theme only.** The token architecture supports a light theme, but none is designed yet; the switcher stays hidden until one is.
- **Desktop-class web only.** The web app targets desktop-class viewports; there is no phone-width layout or mobile app.
- **No tracker import.** See above — a stance, not a gap.
- **No third-party developer platform.** API keys are first-party credentials for your organization's people and agents; there is no OAuth app marketplace.
- **GitHub is the forge.** Repository integration is built on a GitHub App; other forges are not yet supported. Version control is git or Jujutsu (colocated on git).
## Where do I get help?
The [getting started guide](https://stellaloop.com/docs/getting-started/) covers the first loop end to end. For anything else, [contact us](mailto:stella@lorenalabs.com) — including corrections to these docs.
---
# Stella Loop vs Linear-shaped trackers
Product · https://stellaloop.com/vs-linear/
Stella Loop takes the place of your issue tracker — it does not sit beside it. Linear is the reference point for speed and craft in issue tracking; Stella Loop is a different model of development built for teams where coding agents do a growing share of the work. Model differences, not feature checkboxes:
| Dimension | Linear-shaped trackers | Stella Loop |
| --- | --- | --- |
| Organizing model | Issues, projects, and cycles — a fast system of record for work a team has chosen. | A loop: signals feed intents, intents drive analysis, analysis yields proposals, promotion creates epics, review feeds back and seeds the next intent. |
| Where work comes from | People write issues; triage and roadmaps order them. | Feedback from GitHub, Slack, Sentry, and email lands as triageable signals, and analyzers turn the product's current state into scored evidence; promotion decides what gets committed. |
| Product direction | Lives in documents and roadmaps alongside the tracker. | A North Star constellation is a live input — analyzers score against pinned document versions and every piece of work traces back to the aim. |
| Agents | Agent workflows connect through integrations and the API. | Agents are first-class users: the stella CLI, the public API, and a generated MCP server expose every UI capability — parity is CI-checked, not promised. |
| Exploration vs commitment | The backlog holds both ideas and commitments. | The proposal pool separates them: promotion is an explicit, gated commitment point — and competing candidates can race in a tournament, with review selecting the winner. |
| Measurement | Delivery metrics — cycles, velocity, SLAs. | Quality deltas — North Star satisfaction, user experience, maintainability, security — scored 0–100 with versioned rubrics and compared before and after each loop. |
| Traceability | Issues carry a reporter and links you maintain. | A mandatory provenance chain — epic → proposal → report → intent → signal — and, when work ships, a resolution notice can answer the original thread. |
| Human control | Assignment, review, and approvals follow your team's process. | Checkpoint gates are first-class pipeline objects with an autonomy dial — supervised, balanced, autonomous — and hard human gates at promotion and merge by default. |
| Model economics | Not part of the tracker's model. | Per-stage model tiers (frontier / standard / economy), budgets with warn thresholds and hard stops, and truthful per-run cost visibility. |
One honest caveat: there is deliberately no bulk ticket import — imported tickets would bypass the discovery half of the loop. New GitHub issues flow in as signals from the moment a repository is connected; the existing backlog stays where it is.