Init

Init — Project and Personal Root Setup

The explicit setup step that the SessionStart notices point at (/task-orchestrator:init for a project, /task-orchestrator:init --user for a personal root). It creates or finds a root work item, records its id in a project: block of the right config.yaml, pushes that config to the server, and makes sure the bundled process rules are present for that root.

Mode: --user in $ARGUMENTS selects the personal-root flow. Any other non-flag text is the project (or root) name. No flag means project mode.

Everything is created through MCP tools; the skill never creates roots over REST.

Step 0 — Resolve paths

Resolve the plugin root: try ${CLAUDE_PLUGIN_ROOT} (confirm the literal string ${CLAUDE_PLUGIN_ROOT} did not survive into the command you are about to run); otherwise use the dev-checkout path <git toplevel>/claude-plugins/task-orchestrator. Call it <plugin root>.

Print the locator's view with one command (forward slashes only, no backslashes anywhere in it, because the Bash tool collapses them):

node --input-type=module -e "const m = await import('file:///<plugin root>/hooks/config-locator.mjs'); const l = m.locateConfig(); console.log(JSON.stringify({located: l, userHome: m.userHome(), userConfig: m.userConfigPath(), userClient: m.userClientPath(), TASK_ORCHESTRATOR_HOME: process.env.TASK_ORCHESTRATOR_HOME || null, AGENT_CONFIG_DIR: process.env.AGENT_CONFIG_DIR || null}, null, 2))"

Use the drive-letter form with forward slashes on Windows (file:///D:/...). If the plugin root cannot be resolved, derive the same paths by hand: the user home is $TASK_ORCHESTRATOR_HOME when non-empty, else the OS home; the user config is <home>/.taskorchestrator/config.yaml; the client file is <home>/.taskorchestrator/client.json.

Every later message names files by these resolved paths, never a hard-coded ~.

Step 1 — Verify the server

Call get_context(). If the Task Orchestrator MCP tools are absent or the call errors, stop and point the user to /task-orchestrator:configure-server.

Project mode (default)

P1 — Find the main checkout root

The target root is the parent of git rev-parse --path-format=absolute --git-common-dir (this resolves to the main checkout even from a linked worktree). Not a git repository: use the current directory. Call it <main>.

• Refuse a home directory. If <main> equals any home (userHome(), os.homedir(), or os.userInfo().homedir), stop: a config directly in a home directory is never a project config. Offer /task-orchestrator:init --user instead.
• Warn on AGENT_CONFIG_DIR. When it is set, its config shadows the one about to be written; say which file wins.

P2 — Already initialized?

If <main>/.taskorchestrator/config.yaml exists with a non-empty project.rootId, the project is initialized. Skip to P5 (push), then the P5b client.json step, then Rule seeding, so an already-initialized project still gets its client.json. Re-running is idempotent.

P3 — Find or create the anchor

query_items(operation="search", type="project", depth=0)

Drop any item tagged personal-root from the results.

• Matches remain -> AskUserQuestion: attach to one of them, create a new anchor, or abort. Attaching uses that item's id as rootId.
• No matches -> census the depth-0 roots with query_items(operation="overview"). If roots exist other than the global containers (Session Retrospectives, Improvement Proposals, agent-observation items, type=project items), the database already holds unscoped work. Offer via AskUserQuestion: hand off to /task-orchestrator:adopt-project-scope (it creates the anchor, re-parents the work and writes the config; init then resumes at Rule seeding), create a fresh anchor and leave those roots alone, or abort.
• Nothing but global containers -> create a fresh anchor.

Name: from $ARGUMENTS, else the main checkout's directory name; confirm with the user. Create it at depth 0:

manage_items(operation="create", items=[{title: "<name>", type: "project", priority: "low"}])

P4 — Write the project: block

Write at <main>/.taskorchestrator/config.yaml:

project:
  rootId: "<anchor-uuid>"
  name: "<name>"

Read-modify-write surgically: preserve all other content byte for byte; update an existing project: key in place rather than duplicating it. Create the file with only the block when it does not exist.

P5 — Push to the server

If a manage_project_config tool is available, push the full current file text:

manage_project_config(operation="push", rootId="<anchor-uuid>", configYaml="<full file text>")

• Success: the returned fingerprint confirms it; re-pushing identical content returns the same fingerprint.
• VALIDATION_ERROR: show the parse error; the local write is saved, so tell the user to fix the file and re-run (or /manage-schemas validate).
• CONFLICT_ERROR (superseded): the server holds a newer config. Fetch it with manage_project_config(operation="get", rootId=...) and reconcile, or pass force: true only if overwriting is intended.
• A warning field: relay it (non-fatal).
• Tool absent: note it and continue; the local file is authoritative.

P5b — Project-level client.json

So the config-sync and other hooks can reach the REST API without an environment variable. The API URL resolves in this order: TASK_ORCHESTRATOR_API_URL, then apiUrl in a client.json beside the located project config (and, in a linked worktree, the one in the main checkout), then apiUrl in the user-level client.json; if none resolves the hooks do nothing.

1. Run apiBaseUrl() (and, below, isLoopbackApiUrl()) from <plugin root>/hooks/api-client.mjs with a one-liner like Step 0:

   node --input-type=module -e "const m = await import('file:///<plugin root>/hooks/api-client.mjs'); console.log(JSON.stringify(m.apiBaseUrl({cwd: '<main>'})))"

   A URL resolves: skip, with one line naming it.
2. Otherwise find the registered http MCP entry and derive and health-check <base> exactly as U4 steps 1-3. Stdio or an unhealthy server: skip with one line.
3. Check the host with m.isLoopbackApiUrl("<base>"). A project-level file is honoured only as a bare loopback origin: an http/https URL without credentials whose host is localhost, an IPv4 address in 127.0.0.0/8, or [::1], with an optional port and no path, query or fragment (a file inside a repo must not redirect the bearer token to a remote host or choose the request path); anything else is ignored silently. When the check is false, do not write the file: say a project-level file would be ignored for this URL, and that a non-loopback server, or one behind a path prefix, needs TASK_ORCHESTRATOR_API_URL or /task-orchestrator:init --user (the user-level file is unrestricted).
4. When true, write <main>/.taskorchestrator/client.json as UTF-8 JSON containing only {"apiUrl": "<base>"}. If the file exists with a different value, show both and ask.
5. Note how the file is found: the hooks read client.json beside the located config first. In a linked worktree, when the client.json beside the worktree's own config yields no usable loopback URL, the hooks also read .taskorchestrator/client.json in the main checkout, under the same loopback rule. AGENT_CONFIG_DIR pins both files to the directory it names. One file in the main checkout therefore serves every linked worktree. Advise adding .taskorchestrator/client.json to .gitignore: the URL is machine-specific.

P6 — Rule seeding, then advise

Run Rule seeding below, then advise committing .taskorchestrator/config.yaml (and .taskorchestrator/rules/ if present). Never commit client.json.

Close with one line on the orchestration mode, because a located config turns the plugin's orchestration hooks on by default. Read the effective mode from the config just written (orchestration.mode; an absent block means workflow) and say:

Orchestration mode: <mode>. The plugin now injects its orchestration core at session start, denies Agent dispatches that omit model, and adds a dispatch hint after advance_item. Set orchestration: { mode: schema } (no tiers or model table) or { mode: off } (all three hooks silent) in .taskorchestrator/config.yaml to change it.

Do not write the orchestration: block yourself in project mode: absent already means workflow, and init touches this file surgically.

--user mode