Your first project
Press Initialize new project and fill in the wizard.
1. Project name (required)
Section titled “1. Project name (required)”For example, “Annual research plan”.
2. Location and folder name
Section titled “2. Location and folder name”Pick a parent folder as the “location”. AI-POS creates a new subfolder inside it to hold the whole project — the .aipos/, tasks/, artifacts/ structure all lives in that subfolder.
The folder name is derived from the project name automatically (characters Windows disallows are filtered out) and you can edit it; the form previews the final path live. If the location already contains a folder with that name you are stopped and asked to pick another — no existing folder is ever touched.
Want to add AI-POS to a folder that already exists (an old codebase, say)? Use Adopt legacy project from the Projects toolbar instead — what it adds, file by file, is listed below.
3. Domain / description / goals / boundaries (all optional)
Section titled “3. Domain / description / goals / boundaries (all optional)”We recommend filling in at least the goals and the boundaries (what you will not do). These become part of the project’s “constitution”, which the AI respects when it takes over — stored in .aipos/context.json (the source of truth AGENTS.md points agents at), editable there any time after creation.
4. Workflow template
Section titled “4. Workflow template”Determines which phases the project moves through. The built-in templates are:
| Template (id) | Suits |
|---|---|
Generic Workflow (generic-v1) |
Any project |
Software Development (coding-v1) |
Writing code |
Research (research-v1) |
Research, literature, reports |
Business Planning (business-v1) |
Business planning |
Life Planning (life-v1) |
Personal goals |
Built-in templates are bilingual — switch the interface to English and the names, phase descriptions, and AI instructions all switch too. The language in force when you create the project is what gets written into the workspace (it does not follow the interface language afterwards; custom templates are in whatever language you wrote them in).
If you are not sure, pick Generic. You can edit .aipos/workflow.json directly later to adjust.
Want your own process? Go to the Templates page in the sidebar (an app-level item — you don’t need a project open) and add a custom template. Click any built-in template card to inspect it read-only, then press New from this to copy and modify it. The editor is full-page: arrange the phase order on the left, and edit the selected phase’s description, AI instructions, and exit gates on the right (gates are chosen as cards, each with an explanation). The template id is generated from the name, so you don’t have to invent one.
Custom templates live in ~/.aipos/templates/ and are shared machine-wide, so any project you create afterwards can use them. Dropping a JSON file into that folder by hand works too (a matching id shadows the built-in version).
5. Track this workspace with git (optional)
Section titled “5. Track this workspace with git (optional)”Only shown if git is installed on your machine. Ticked by default. With it ticked, AI-POS runs git init after creating the project and makes the first commit, so you can track every change with git from then on. If the new workspace folder is already inside a git repo (the location you picked is itself version-controlled), this is skipped automatically — it uses the outer repo rather than creating a nested one.
6. Capability modules (all optional, all off by default)
Section titled “6. Capability modules (all optional, all off by default)”A fresh workspace ships with none of them enabled — tick only what this project needs:
| Checkbox | What it adds |
|---|---|
| Enable the collaboration module | Assignees and prerequisites on tasks, an assignee kanban, and an agent activity feed — for when several people or several AI agents work in parallel (see Multi-agent collaboration) |
| Enable the specs module | A specs/ tree recording what the system does now; task deltas fold in when the task is verified and archived. Your agent’s operating protocol prompts it to write a delta for any task that changes behaviour — the folding is enforced, the writing is prompted |
| Enable the team module | An Inbox page, and the delivery hub tools, so this project can exchange work with others (see Teams) |
Solo projects need none of them. You can change your mind at any time from the workspace’s Project settings page (while that project is open) — enabling one late loses no data. Joining a team turns the team module on for you automatically.
7. Press “Create workspace”
Section titled “7. Press “Create workspace””You land on the dashboard. Three moves turn the empty shell into the thing this product is for:
- Create the first task (Tasks page) — even a rough one. The Generic template’s first phase waits on exactly that: its only exit gate is
min_tasks(1). - Connect your agent — open your agent CLI in the project folder (or on the Terminal page); it picks the project up from
AGENTS.md. - Press “View snapshot” on the dashboard — that regenerating handoff file is what “the next session picks up the thread” means in practice. It is the thing you just bought.
Adopting an existing folder instead
Section titled “Adopting an existing folder instead”Adopt legacy project (Projects toolbar) runs the same scaffolding against a folder that already exists — an old codebase, a research directory. It only ever adds — with two deliberate, disclosed edits inside files you may already own: an existing CLAUDE.md gets an @AGENTS.md import appended (never rewritten or reordered — the smallest edit that makes the takeover layer reachable), and an existing .mcp.json gets the aipos server entry merged in (every other server entry you have is left untouched; an old aipos entry is re-pointed). Everything else that is already there stays exactly as it was.
What appears in your folder, all of it plain text:
.aipos/— engine state: context, rules, the instantiated workflow, the ledger, snapshots, sealed secrets, the day-one tool grants (agent_access.json), the shipped-asset fingerprint, plus a three-line.gitignorecovering the machine-local filestasks/,artifacts/— the work itselfAGENTS.mdandCLAUDE.md— the agent entry point and its one-line Claude shellproject.yaml— the human-readable manifestaipos_docs/— the operating guide agents read (00-protocol.md,01-aipos-guide.md, plus one guide per enabled module)memory/MEMORY.mdandwork_record/_TEMPLATE.md— the cross-session memory index and the monthly work-report template.mcp.json,.agents/skills/and.claude/skills/— hub wiring and the four bundled skills
Commit the lot minus what .aipos/.gitignore already excludes (see the FAQ). If the folder was already under git, nothing is re-inited — the additions simply show up as an ordinary diff to review, which doubles as the complete list of what adoption touched.