Connect an AI agent

This is the core scenario for AI-POS. The division of labour: AI-POS is the management hub, the AI agent does the execution.

Wiring it up (one-time)

1. There is nothing to build or put on your PATH. The app’s own build step compiles aipos-mcp and bundles it alongside the app; a workspace you initialised already contains .mcp.json in its root, pointed at that executable’s absolute path. There is no background service to start or keep running: the agent host spawns aipos-mcp itself through that file, once per session, and it exits with the session.
2. The Claude CLI picks .mcp.json up and connects to the hub automatically when it opens that folder. Other vendors’ CLIs wire up MCP differently and do not — consult their own documentation.
3. To check the connection, go to the Tools page and look at the aipos-mcp health card. Ready means it is wired up. Needs repair (for example after you rebuilt the executable) means press Repair connection to re-point it — it repairs the pointer in .mcp.json, there is no running process to restart. Executable missing means the hub binary could not be found at all — neither bundled beside the app nor on your PATH; rebuild the app, then repair here.

Any other MCP client

The hub is a plain stdio MCP server — nothing about it is Claude-specific. What the Claude CLI reads from .mcp.json is this (with command rewritten at init time to the bundled executable’s absolute path):

{
  "mcpServers": {
    "aipos": { "command": "aipos-mcp", "args": ["--workspace", "."] }
  }
}

To wire up any other MCP client, copy that command and args into its own configuration. Two things to know:

• --workspace . resolves against the directory the server is spawned from. Claude Code spawns it from the project root, so . works; if your host spawns servers from somewhere else, replace . with the workspace’s absolute path. Getting this wrong is loud rather than silent — the server prints not an initialized AI-POS workspace to stderr and exits with code 2 — but some harnesses swallow server stderr, so if the server “just won’t start”, check this first.
• Full usage is aipos-mcp --workspace <root> [--agent <name>]. --agent names the caller in the ledger; the AIPOS_AGENT environment variable does the same, and the flag wins when both are set. Worth setting even for a single agent, so the audit trail says who did what. (Several agents in parallel, each under its own name, is the multi-agent setup.)

To verify the wiring on any client: have the agent call workspace_status — read-only, needs nothing beyond the master switch — then look at .aipos/ledger.jsonl. Every hub call lands there, so one entry proves the connection end to end.

Authorisation (you are in control)

On the Tools page:

• At the top is the master switch, “Allow agents to reach the hub”. Turned off, the AI can’t even use read-only tools — it is fully disconnected.
• With the master switch on, Read-only tools (always allowed) (list tasks, view the workflow, search, doctor, and so on) need no per-item setup.
• Write tools (granted by capability group) (create tasks, change status, record decisions…) are authorised by group. Each group has a name and a plain-language description (task editing, knowledge recording, phases and milestones, …); ticking a group opens every tool in it. Expand Per-tool to control them one by one, or use Select all to open everything.
• New projects don’t start from zero. At creation, the everyday recording and flow tools are already authorised, so an agent can do useful work the moment it connects. Only these five are off by default, because they are the checks themselves: marking something verified (set_task_verification / set_milestone_verified), advancing a phase (advance_phase), packaging a delivery into this workspace’s outbox (publish_delivery), and rewriting workspace assets (upgrade_workspace_assets). You have to open those yourself. (Projects created before this default are not retroactively changed — they remain fully closed; one press of “Select all” fixes that.)
• Every call is written to the ledger — including rejected ones — so it can be audited afterwards.
• You find out immediately when a call is denied. If an AI calls an unauthorised tool, a toast appears in the bottom right (“⟨agent⟩ was denied ⟨tool⟩ — not authorized yet”) with an Authorize button. Repeated attempts at the same tool don’t spam you; they collapse into one entry with a count. Without that toast the AI would just sit there waiting and you would never know.
• Grants take effect on the agent’s next call. The server re-reads the allowlist from disk per call, so there is no session to restart — authorise the tool and tell the agent to try again.
• An AI has no permission to force a phase advance or to satisfy a manual confirmation gate. Those two are permanently human-only.

Where the allowlist ends

The allowlist governs the hub tool surface: the structured operations above, each checked per call, each ledgered. It does not govern your agent’s own hands. A coding agent with file access can edit any file in the workspace directly — including .aipos/ state, and including agent_access.json, the allowlist itself. Those hands are your agent CLI’s permissions to grant or withhold, not AI-POS’s; the openness is the price of files-are-truth, the same property that lets you fix anything with a text editor. What holds regardless: gates are evaluated against real state, manual_confirm has no tool surface at all, and the file watcher picks up hand edits — but a hand edit is not a ledgered call. Read the ledger as the record of what agents did through the hub, not of everything that happened to the folder.

Actually using it

Open a Claude Code session in the project folder. The first time, the CLI asks whether you trust this project’s .mcp.json — allow it, and every subsequent session connects automatically.

It then reads the root CLAUDE.md, a one-line shell importing AGENTS.md — whose state block the engine keeps fresh (current situation, this phase’s instructions, gate list, next step) — picks up the work from there, and reports tasks and decisions back through the hub tools. You watch the progress arrive in the app live.

The bundled skills

Initialising a workspace also places the general-purpose workflow skills in .agents/skills/, with identical copies in .claude/skills/ where Claude Code discovers them (you can customise them — edit both, or the doctor will flag the mismatch):

• Hand over a broad or vague direction and /align-scope settles what “done” means before any work starts — one question at a time, decisions left to you.
• Say “wrap up” to Claude Code and it runs /wrap-up — commit in batches, run the doctor, write progress and decisions back into the project.
• “Check that this can be handed off” runs /handoff-check — self-audit for unrecorded facts, then dispatch a brand-new agent to cold-read the handoff documents and verify a takeover actually works.
• After large documentation changes, /adversarial-review dispatches an agent to check each claim in the docs against reality.

Step 7 of the session operating protocol instructs agents to invoke all four proactively at the right moments, without waiting to be asked. Naming them yourself is a backstop, not a requirement. If your agent host has no concept of skills, each one is plain Markdown at .agents/skills/<name>/SKILL.md — readable and followable as a procedure.