A tour of the app

Projects (home screen)

Opening the app lands you on Projects: every project you have opened, listed as cards — name, path, template, domain, current phase, task completion count, last opened, and a “terminal running” marker if it has a live session. Click a card to enter that project.

The sidebar always shows Projects (the first item under the branding area), and below it the workflow template categories (each built-in template plus “custom templates”). Categories with no projects fold behind a single “N more categories” row — click it to list them too; the selected category is never folded away. A “no template” category shows up only if you have legacy workspaces. Click a category to filter. Once you enter a project the categories collapse to make room for the project’s own pages — click “Projects” to come back, and they expand again.

Projects you have opened stay in the list: they are never pushed out to make room. Hover a card and an × appears in its top-right corner; pressing it asks for confirmation first, then removes the project from the list. That only removes the shortcut — it deletes no files. Use it to clear out entries marked “missing” too.

The toolbar in the top right has four actions. (The first time you use the app, with no projects yet, these appear as entry cards in the middle of the screen instead.)

Action	When to use it
Open workspace	The folder is already an AI-POS project (it contains .aipos/)
Initialize new project	Starting a new project from scratch — the most common first step, see Your first project. Opens as a dialog
Adopt legacy project	You already have a folder in progress (an old codebase, say) and want to add the AI-POS management layer. It analyses read-only first, drafts a description and tasks for you to confirm, and never overwrites existing files
Import backup	Restore a .zip backup brought from another machine (requires the passphrase that sealed its machine-local data — see Backups)

Already inside a project and want to switch to another one? Click the current workspace name in the sidebar to open a quick-switch menu, or click “Projects” to go back to the home screen and pick one there (the current project stays open).

Pages in a workspace

The sidebar runs top to bottom. The items at the top (Projects and the template categories, Teams, Agent sessions, Templates, Settings) are cross-project: see the section above for Projects, Teams for teams, The built-in terminal for agent sessions, and Your first project for templates. Everything below is scoped to the current project.

Dashboard

The state of this project on one page, top to bottom: what this phase still needs to advance, the workflow panel (current phase, this phase’s AI instructions, exit gate checklist, advance button), the task overview tiles, milestones, and recent activity (the latest window of the event ledger — “view all” in the top right jumps to the Ledger page).

You can also record a decision, progress note, or note here. (“Progress” means the wrap-up summary of one round of work; it surfaces in AGENTS.md under “last progress” so the next AI session sees it first.) You can generate a handoff snapshot manually, or press View snapshot to read .aipos/snapshots/latest_handoff.md in full — the first document a new AI session should read. The viewer lets you copy it or regenerate it.

Tasks

Create and manage atomic tasks. The status flow is todo → in progress → done; if you get stuck, mark it blocked (a reason is required). The reason is shown with how long ago it was written — nothing re-checks a blocker, so a reason from three weeks ago is a claim to re-test, not a current fact.

Marking a task done only means “claimed done” — there is a separate verification mark, which requires attaching evidence (what you ran, what you saw). If you mark a task done without evidence, the page prompts you to add it. (You can dismiss that prompt permanently, and re-enable it under Settings → General.) Any status change regenerates the handoff snapshot automatically.

Made a mistake or a typo? Press Edit to change the title, description, priority, or tags. Status, verification, archiving, and assignment each have their own controls — editing does not touch them, and does not invalidate an existing verification. Press Delete for tasks you don’t want: after confirmation the task file is gone, but the ledger keeps a record including the title, so you can look up what you deleted. If the task had an artifact bundle (tasks/T-XXXX/), deleting the task deletes the whole bundle with it: proposals, design notes, and spec deltas included. If other tasks depend on this one, the delete is blocked and you are told which tasks depend on it — resolve those dependencies first.

When you have a lot of tasks, use the filter bar at the top (search title/description/ID, filter by status, filter by tag, and sort by ID, priority, or last updated). Clicking a tag chip filters by that tag.

Long-running projects accumulate completed tasks — archiving clears them out. Individual done tasks can be archived, or use Archive verified done to sweep them in one press. Unverified tasks are not swept, so they stay visible as a reminder to add evidence. Archiving only hides tasks from the list (tick “Show archived (n)” to see them, and you can un-archive) — the files and history remain.

Verified done tasks are also archived automatically: each time you open the workspace, the engine archives tasks that have been verified-and-done for N days (on by default, N = 7). The archive row has a switch and a day count — turn it off if you would rather sweep by hand.

Collaboration (only when the collaboration module is enabled)

A task board with one column per assignee, including an “unassigned” column; reassign directly on the cards. Click a column heading to fold that column away — the name and count stay, so a board with a dozen assignees can be narrowed to the ones you are working with. Tasks with prerequisites show a lock marker and unlock only when every dependency is done — if you try to start early the engine blocks it and tells you who you are waiting on. Below the board is the agent activity feed: which agent called what, recently.

Specs (only when the specs module is enabled)

The curated record of what this project does right now. On the left is the list of capability areas (specs/<capability>/spec.md in the workspace root — one file per area, git-trackable); click one to read its Markdown.

Below that, the pending folds panel lists in-progress tasks that have written spec deltas (change proposals under tasks/<task-id>/specs/). When a task is verified and then archived, the engine folds its delta into the main spec automatically. If there is a conflict the archive is blocked and the conflicts are listed — fix the delta and archive again.

The page is read-only: specs are just files, so edit them in your editor or hand them to an agent. The folding is what the engine guarantees, at the moment of archiving.

Format. Specs use an OpenSpec-compatible structure: ### Requirement: headings (the trimmed heading text is the requirement’s identity) each containing at least one #### Scenario:. A task’s delta file uses four sections — ADDED, MODIFIED, REMOVED, RENAMED — and a MODIFIED requirement must be rewritten in full rather than patched. Agents write these with their own file tools; the engine only validates and folds (validate_task_specs checks a delta before you rely on it).

Inbox (only when the teams module is enabled)

Deliveries that upstream projects have sent you arrive here as envelopes. Each is one row — who sent it, the opening of their note, an attachment count, and when it arrived — and the row’s View button opens the envelope itself, with the note in full and the attachment list. Turn one into a task in one click, or record it as a decision in the ledger. The list shows the 50 most recent with Show older below them; notes have no length limit, so the row clips and the envelope does not.

This is also where you publish your own deliveries: write a note (attachments optional), which packages it into the outbox — then go to Teams in the sidebar to send it (see Teams).

When a new delivery arrives a toast appears in the bottom right and an unread count appears next to “Inbox” in the sidebar. Opening the page clears the count, and the rows that were unread stay marked — with a dot and a heavier sender — for as long as you are on the page, so a badge that says “3” does not leave you hunting for which three. When you open the app, if a different project has unseen deliveries you get a prompt for that too (click “view project” to go there) — you don’t have to remember to check when someone sends you something.

Ledger

Browse this project’s history. Decisions + progress + notes is the default view (recent activity on the dashboard gets washed out by new events; this doesn’t). You can switch to Agent calls to see only what agents did, or to All events (tasks, gates, and so on). Entries are grouped by date, with “load more” to page backwards — a single view has a display limit, but the complete history always lives in .aipos/ledger.jsonl. You can record decisions, progress, and notes from here too.

Search

Full-text search across the code and documents in your project. Press Build index the first time. The index is a rebuildable derivative — the files are the source of truth.

Tools

Top to bottom:

• Workspace doctor: one press to check whether the handoff layer is healthy: broken links, stale handoff, outdated engine curriculum, and so on. Read-only, changes nothing. (Two words this page uses as names: the handoff layer is the set of files an agent reads to take over — AGENTS.md, its CLAUDE.md shell, the operating guide; the engine curriculum is the part of it AI-POS itself ships and versions — the guide under aipos_docs/ plus the bundled skills.)
• Agent access master switch, and below it the aipos-mcp health card — whether this workspace’s .mcp.json points at a hub the app can find, with Repair connection when it has gone stale.
• Workspace assets: after an AI-POS update, upgrade the engine curriculum in your workspace (the operations guide and the general-purpose skills) to the new version in one press. Files you have edited are never touched, and anything overwritten is backed up first.
• Write tools and read tools: control which hub tools an AI agent may call (see Connect an AI agent).

Terminal

Launch an agent CLI (Claude Code, Codex, …) or a plain shell in the project root, without opening a separate terminal window — see The built-in terminal.

Project settings

(Workspace-level; only appears when a project is open, at the very bottom of the workspace pages.) Settings that concern only this project: capability module switches (such as the collaboration module), the AI takeover layer — another name for the handoff layer above (press Fill missing files to add AGENTS.md, its CLAUDE.md import shell, and the rest of those files to an older workspace in one press), Export backup, and close workspace.

Templates (app-level)

Manage workflow templates — inspect the built-ins, and add, edit or delete custom ones. See Your first project.

Settings (app-level)

App-wide settings, reachable without opening a project (like Teams): interface language, appearance theme, Agent CLIs (which command-line tools the built-in terminal can launch — the preset agent CLIs and the plain shell are read-only, and you can add your own), and About. Settings tied to a specific project (modules, the handoff layer, backups) live under Project settings above.