Projects, repositories, and work items

Sessions are where agents do work. Projects and work items are where you decide what work is worth doing, who or what is doing it, and whether it landed. The Project Manager holds all of this, stores its data alongside your code, and connects a work item to the agent session that implements it.

Repositories and workspaces

Everything in the Project Manager hangs off an active workspace — normally a Git repository on your machine. Repositories are added at the app level, not inside the Project Manager: the workspace selector groups entries into Repositories and Work Folders, with Pinned, Current, and Recent sections.

Use Add workspace or Add repo..., which offers Create new repo (a Repo Name, Local Path, and an Initialize with README.md option), Clone from GitHub URL, Clone from my GitHub, and Create new workspace for grouping several repos. You can also drag a folder onto the window; if it has no .git directory, ORG-2 asks Initialize Git?

Repo settings

Repo-level settings sit above individual projects and have three sections:

Because members come from git identities, a commit email missing from the list produces "Could not match your identity to any team member" — resync members, or claim it from Suggested Matches.

Projects

A project groups work items. Create one with Add Project. Each project picks a Sync method: Storage (the app's local database) or Git (via .orgii), which writes the project and its work items into a .orgii directory in the repo so they version and review like code.

Project properties include Status (Backlog, Planned, In Progress, Completed, Canceled), Health (On Track, At Risk, Off Track), Priority (Urgent, High, Medium, Low, No priority), Lead, Members, Teams, Labels, Start date, Target date, and Repo(s). Projects are not scoped to a single repository — Link repos attaches one or more workspace repos as a filter dimension.

The dashboard groups projects By Org, By project, By status, By priority, or By target date (bucketed into Overdue, Next 7 days, Next 30 days, Later, No target date).

Project settings also set the ID Prefix — 1–3 letters or numbers, giving IDs like PRJ-0001. Leave Custom Prefix off and it derives from the first three characters of the project name and follows renames.

Work items

A work item is one unit of work. Create one with Create work item, choosing Create with AI, Generate with Agent, or Manual Creation.

The lifecycle runs Backlog → Todo → In Progress → In Review → Done, with Cancelled and Duplicate as terminal states off to the side. Alongside status, an item carries a Priority (No priority, Urgent, High, Medium, Low), an Assignee, a linked Project, a Milestone, Labels, a Start date and Due Date, a Reviewer, and a To-Do checklist (entries capped at 120 characters).

Every change lands in the Activity feed — status moves ("moved from X to Y"), assignment, labels, description edits, comments — each attributed and timestamped. Deleted items go to the Delete Bin, "Recoverable for 7 days", with a Restore action.

Views

Work items are presented on tabs — Overview, List, and Kanban are the ones you switch between day to day, and Gantt, Calendar, and Settings exist alongside them.

• Overview — Statistics (Total Items, Completion Rate) and Recent Updates.
• List — a grouped, filterable table. Right-click an item to change Status, Assignee, Priority, Labels, Project, or Milestone, or to Set due date, Rename..., Add link..., and Favorite.
• Kanban — one column per status, ordered Backlog, Todo, In Progress, In Review, Done, Cancelled, Duplicate. Drag a card to another column to change its status; columns can be reordered too.

Settings opens from the status-bar sync widget rather than the view switcher. Gantt (a 3d/7d/1m/3m timeline with draggable bars) and Calendar (Day/Week/Month) ship in the build, but the current work-items header exposes no control that selects them.

Note: the project Kanban board is not the Kanban page in the Ops Control workstation. That one is a session board — all sessions across every repo, grouped by status with a time-range filter, not tied to any project. They share a board component, which is why they look alike.

Handing a work item to an agent

Assignment is how a work item reaches an agent. The Assignee dropdown groups candidates into Members, Agents, and Organizations — pick a person and it is tracked work; pick an agent or an agent team and the item can execute itself.

Creating an item with an agent assignee attaches an orchestrator configuration. The defaults are conservative: Code Review off, Follow-up Items off, Auto Retry off with Max Retries of 2, and Auto Create PR on. A run also needs a Code Account and model, or it fails with "Please select a code account in Agent Settings before starting."

While a run is in flight the item holds an execution lock, so a second session cannot start on it — a scheduled routine set to Re-run an existing work item refuses rather than trampling an active run.

Results land on the item's Output tab: the Pull Request and its state (or a Create Pull Request button if none exists), Changed Files with per-file diffs, review feedback, and a Cost Summary in dollars, tokens, and cycles.

Branches and worktrees

The branch an agent worked on is recorded in the item's proof of work, not created by the Project Manager. Branches appear one of two ways: a session launched with isolation gets its own git worktree on an agent/<session-id> branch under ~/.orgii/agent-worktrees/; otherwise the agent is told in its prompt to create a feature branch if one does not exist. Concurrent worktrees are capped per repository (default 8), with stale ones pruned on a timer.

Linking a session to a work item

From the other direction, a chat session can be attached to a work item. The composer's Add Work Item control lets you Link an existing item — search by title or ID — Create a new one inline, or Remove the attachment. The item's short ID then travels with the session, so its cost, transcript, and file changes roll up under Linked Sessions. Items produced by a scheduled routine are labelled From routine: {name}; see Scheduling.

Linear

There are two distinct ways to work with Linear, and they do different things.

Linear Projects is a live browser — browse and edit Linear Projects in real time without importing them. Issues are read and mutated directly through the Linear API; nothing is copied locally. Create a Linear connection in Integrations first, or the page shows No Linear connections. You then get a Project list, live Linear Issues, Create Project, Create Issue, Archive, and Refresh actions, and a Linear Project Info panel for editing Workflow states. Only an issue's title, description, priority, and status are editable — anything else returns "This Linear Issue field cannot be edited in ORGII yet."

External Sync is the mirroring path, configured per project under Settings → Sync: "Mirror this project's work items to an external system like Linear or GitHub." Attach an Adapter, pick the global Account it uses, and authenticate with either OAuth or a Personal token — "Either method works — the most recent sign-in wins."

Once attached, sync runs continuously in both directions. Historical import walks the full remote history once on the first sync, then later cycles go incremental. An optional Webhook lets the provider push changes instead of waiting for the next poll — paste the URL and signing secret into your provider's config; the secret is shown once and not stored in plaintext. Status reports Last pull plus Pending, Failed, and Abandoned counts, with Force push, Force pull, and a Failed entries list you can Retry or Discard.

Sync conflicts pause on divergence rather than overwriting. Each shows the Local and Remote value per field; resolve with Keep local, Adopt remote, or Dismiss.

Not every field round-trips. For Linear, title, description, priority, dates, assignee, and labels are written back, but status is read-only in the sync direction — mapping a work item status onto a Linear workflow state needs per-team state configuration that is not yet exposed.

Next steps

• Scheduling — run work items and sessions on a schedule
• Sessions — what happens once an agent starts on a work item
• Agents — configuring the agents you assign work to
• Collaboration — members, teams, and shared orgs