FAQ

Can I edit the files in my project by hand?

Yes. The files are the source of truth — editing a task JSON or context.json by hand is a legitimate operation, and the app reflects it live through its file watcher.

Two kinds of file inside .aipos/ should be left alone, though: rebuildable derivatives (snapshots, indexes), and the append-only event ledger ledger.jsonl (the authoritative audit record).

Will the AI mess up my project?

Write tools are authorised by you, by capability group (expandable to individual control). When a new project is created, the everyday recording and flow tools are pre-authorised (create tasks, change status, record decisions/notes/lessons…) so an agent can work as soon as it connects. Five gatekeeping tools, in four categories, are off by default and you have to open them yourself: marking things verified (set_task_verification, set_milestone_verified), advancing phases (advance_phase), packaging a delivery into this project’s outbox (publish_delivery), and rewriting workspace assets (upgrade_workspace_assets). Four of the five exist in every workspace; publish_delivery arrives with the team module — which is why a fresh workspace counts 12 of its 16 write tools granted and 4 held behind a guard, while this page says five.

Every call goes into the ledger. Phase gates are judged by the engine against real state — an AI cannot declare its own pass.

One boundary to keep in view: the allowlist governs the hub tools. An agent’s own file editor is governed by your agent CLI’s permission system — AI-POS deliberately keeps the folder open to hand edits, yours and your agent’s alike. Where the allowlist ends draws the line precisely.

I already keep a CLAUDE.md and a TODO list in git. Why an app?

That setup is what AI-POS grew out of, and the medium stays the same — plain files in your folder, under git. What hand-kept markdown cannot give you is the part that has to stay maintained and checked: the handoff snapshot regenerates on every state change instead of when you remember; “done” is a gate the engine evaluates against real state, not a checkbox anyone — you or the agent — can tick in a file; every hub call an agent makes lands in an append-only ledger, granted or denied; and the doctor machine-checks the broken links and staleness you would otherwise proofread yourself. If you keep that discipline reliably by hand, you may not need this. The app is for the days you don’t.

What should I commit, and what should I ignore?

Commit everything the wizard did not already ignore. Initialisation writes a three-line .aipos/.gitignore covering the machine-local files — secrets.enc (sealed by this machine’s key), index.sqlite (a rebuildable search index), .mutex (a transient lock) — and everything else is designed to travel with the repo: tasks, the ledger, snapshots, AGENTS.md, specs. The ledger and the current snapshot are the project’s history and its handoff — exactly the things you want in version control.

I switched machines, or haven’t touched a project in ages. How do I pick it back up?

Read the handoff snapshot — press View snapshot on the dashboard, or open .aipos/snapshots/latest_handoff.md directly. Which phase you’re in, how far you got, and what comes next are all in there.

Will the project documentation rot (broken links, stale information)?

The Tools page has a workspace doctor that machine-checks in one press: broken links, stale handoff, missing handoff files, and so on. Error-level problems also block phase advances, if the template has a doctor gate.