¶Concepts

Ten words carry the whole product. They are ordinary on purpose: this is a task tracker where some of the workers happen not to be human, and inventing vocabulary would only make that harder to see.

¶The hierarchy

Workspace          the company — the tenant boundary
└── Project        work that has been committed to, with a lead and a target date
    └── Epic       a container issue, grouping related work
        └── Issue  the unit of work
            └── Task   one run of one agent against that issue

Only Workspace → Issue is mandatory. A project is optional, an epic is optional, and an issue worked on by a human never has a task at all.

¶Workspace

The tenant boundary, and the coordinate system for everything else. Issues, projects, agents, runtimes, skills and members all belong to exactly one workspace, and nothing crosses between them.

A workspace carries an issue prefix (ACME) and a counter, so issues get human identifiers like ACME-42. It also carries context — a system prompt prepended to every agent's own instructions — and a repository allowlist, which is the only set of repositories an agent may check out.

¶Member

A user's role inside one workspace: owner, admin or member. The same person can be an owner in one workspace and a member in another.

This is not the same as being a platform administrator. See Permissions.

¶Project

A portfolio-level container. Status (planned, in_progress, paused, completed, canceled), priority, a lead — who may be a person or an agent — and an optional target date.

Progress is measured, never reported: the percentage is closed issues over total issues, computed on read. A project also configures which issue types its issues may use.

Deleting a project keeps its issues. They simply lose the grouping.

¶Issue

The unit of work. Title, rich-text description, acceptance criteria, and:

on_hold is a status rather than a type, because it describes where the work stands, not what kind of work it is.

¶Epic

An issue whose type is epic. It contains other issues through parent_id, and its progress is measured in closed children.

Three rules, each enforced and tested:

• Only an epic can be a parent
• An epic cannot be filed inside another epic
• An epic with children cannot stop being an epic

See Working with epics.

¶Agent

An AI worker with a name, a description, a provider, a runtime, instructions, environment variables, extra CLI arguments, a concurrency limit and a visibility setting.

An agent is not a model. It is a configured worker identity that happens to be backed by a CLI. It appears in the assignee picker beside people, comments in threads, and shows up in the audit log — through the same columns as any human.

Agents are archived, never deleted: their name appears on issues, comments and runs that must keep making sense.

¶Runtime

A machine that can execute agent work — specifically, one agent CLI on one machine. A laptop with both claude and codex installed registers as two runtimes.

A runtime is online when it has sent a heartbeat within the last 45 seconds. That is computed, not stored, so a crashed daemon cannot leave a runtime looking alive.

¶Task

One run of one agent against one issue. This is the distinction that matters most: an issue is what should be done and lives forever; a task is one attempt at doing it and carries status, session id, working directory, attempts and how long it ran.

One issue, many tasks. The queue lives in the status column rather than in Redis, because it has to be visible in the interface and claimable by an external process.

queued → dispatched → running → completed
                    ↘ failed (retryable → back to queued)
                    ↘ canceled

Session resumption: the next task for the same (agent, issue) pair reuses the previous session_id and work_dir. The agent continues its own conversation instead of starting cold.

¶Artifact

What a run handed over. The summary says what happened; an artifact says where it is.

A pull request, a branch, a commit, a document, a link. They appear as chips on the issue, beside the agent's summary comment — where a colleague would have put one.

Félagi knows nothing about GitHub, and that is the design rather than an omission. An issue here can be about code, a document or an analysis, so building one host's model of "a pull request" into the core would make every other kind of work second-class. The agent opens the pull request itself, with gh or glab, because a skill told it to. Félagi stores a link and a state.

Two consequences worth knowing:

A pull request moves the issue to In review. The one place an agent changes an issue's status, and narrow on purpose — never from a status after review, never for a branch or a link.

Nothing polls. A merged pull request stays marked open here until something says otherwise. There is a webhook for that, and it takes a URL and a state so any forge can post it.

See Delivering work.

¶Timesheet

One person's hours, laid out over the days they were spent on. Not a second system: the same time_entries rows an issue writes, read a week at a time.

The distinction from a report is what it is for. A report aggregates and asks "where did the hours go"; a timesheet shows the empty days, because "what have I forgotten" is the question somebody actually has on a Friday afternoon.

Expected hours come from the same weekly rate the Gantt and cycles use. An agent's hours appear beside a person's and can be edited by nobody — the run is the record.

See Timesheets.

¶Article

A page in the knowledge base, nested arbitrarily deep. Unlike an epic, which is one level on purpose: a plan with grandchildren stops being readable, and documentation is the opposite because the nesting is the organisation.

The row is metadata; the prose is a file under storage/knowledgebase. A tree of four hundred articles is drawn on every page load and none of it needs the text — and the documents stay greppable, rsyncable and readable without a database client, which is worth something for the page about restoring the database.

See Knowledge base.

¶Whiteboard

An endless surface, and deliberately the least structured thing in Félagi. Everywhere else a piece of work needs a title, a type and somewhere to live; here it needs a position.

What separates it from a drawing tool in another tab is the wire back to the data model: a note becomes a real issue and stays on the board pointing at it, and an issue already in Félagi can be dropped on as a card showing its live status.

Shared with the workspace by default, or private to whoever made it. Cursors are whispered browser to browser and never reach the server.

See Whiteboard.

¶Label

A word on an issue, and nothing more. Created on use, deduplicated case-insensitively, coloured by a stable hash of the name.

No settings page to visit first — a team that has to define needs-design before they can write it down writes it in the title instead. Two labels filter with AND, because an issue carries several and picking a second one asks for the overlap.

¶Attachment

A file hanging off an issue, a comment, an article or a whiteboard, through one polymorphic table.

Served by the application rather than from a public folder: a file on a public disk is readable by anybody who guesses the URL, and these are screenshots of somebody's production incident. The stored path is a random ULID — a path derived from a filename is a filename that can be a path.

¶Cycle

A fixed window of time, generated on a cadence. Not a sprint: there is nothing to open, nothing to name and nothing to close.

The distinction matters for two reasons that are specific to this product. Agents do not attend planning meetings — they work continuously, which is the point of them — and capacity here has always been a rate rather than a rota, so a window is a view over the existing timeline rather than a separate plan competing with it.

Two consequences worth knowing:

Unfinished work moves into the next window, and the moves are counted. "Carried for four cycles" is the most useful number a planning tool produces and the one most of them hide.

Capacity includes the machines. An agent's weekly hours count exactly as a person's, so "planned 6 days against 40 days of capacity, half of it machine" is a sentence Félagi can say.

See Cycles.

¶Skill

A markdown document describing how your team does something. Attach it to an agent and the daemon writes it into the work directory before the CLI starts — at the path that CLI already looks in (.claude/skills/…, .codex/skills/…, .elyra/skills/…).

A skill is not a prompt template and not code. It is the thing you would otherwise explain to a new colleague, and then explain again.

¶Comment and activity

Comments are rich text authored by a person or an agent. Mentioning an agent (@Freya) hands it the thread: a run is queued exactly as if it had been assigned.

Activities are the audit log — every status change, assignment and run event, with a polymorphic actor that may be a user, an agent, or nothing at all when the system acted on its own.