jpicklyk/task-orchestrator/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 registers the MCP entries, creates or finds a root work item, records its id in a project: block of the right config.yaml, validates and 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. --no-director skips the director registration (Step 2). Any other non-flag text is the project (or root) name. No flag means project mode.

Not a director-mode skill: run it outside director mode (/task-orchestrator:director off); director-guard denies its file, shell and config steps partway through.

Everything is created through MCP tools; the skill never creates roots over REST. Every call below is a to-call block, {tool, select|op, args}, in the shapes of call-shapes.md.

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

Read the health view (orchestration profile):

{"tool": "items_read", "select": "context", "args": {"limit": 5}}

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

Then confirm the server is 4.x: runs_read must be among the tools you can call (a 3.x server has no run tools). If it is absent, the server is 3.x or older and this plugin's majors do not match it: stop and point the user to the "Upgrading from 3.x" step of /task-orchestrator:configure-server.

Step 2 - Register the MCP entries

Both modes, once the server answers. Locate the orchestration entry the way hooks/session-start.mjs does: .mcp.json mcpServers, then ~/.claude.json mcpServers and projects[<dir>].mcpServers; an entry counts when its key contains task-orchestrator. An HTTP entry carries url (ending /mcp); a stdio entry carries command and args. Note which file holds it.

The director entry. Unless --no-director was given, make sure a second entry exists next to the orchestration one. Its key must contain task-orchestrator (the plugin's hook matchers key on it), so use the exact key mcp-task-orchestrator-director (claude --agent task-orchestrator:director looks for that key).

• stdio, `docker run` entry: the orchestration entry's command and args, with -e MCP_TOOL_PROFILE=director inserted before the image name.
• stdio, any other command (JAR, local binary): copy the entry and set env: {"MCP_TOOL_PROFILE": "director"}.
• HTTP: the orchestration entry with url set to <base>/mcp/director (<base> is the orchestration URL without its trailing /mcp).

Say why it exists: a single developer on one stdio server has no HTTP endpoint for the director tools, and a run-budget or attempt-cap decision is answered through a second stdio entry started with MCP_TOOL_PROFILE=director (fleet deployment). That profile serves only read, run-control and decision operations, and no read that returns a note, document or transition-summary body (API reference, tool profiles). Both stdio processes share the database volume and act as the one local principal. On the first 4.0 start over a 3.x volume, follow the "Upgrading from 3.x" step of /task-orchestrator:configure-server first and start the orchestration entry alone; a second concurrent first boot waits on the migration lock and can fail the schema update on a large database.

Existing entries. Detect a director entry by the exact key mcp-task-orchestrator-director. When found, report it and leave it alone, with two checks:

• Its Authorization header uses ${TASK_ORCHESTRATOR_API_TOKEN}: say it shares the agents' credential, and offer via AskUserQuestion to switch it to the director placeholder below. Before switching, remind the user that the director token-file entry (configure-server "Director credential") must exist and TASK_ORCHESTRATOR_DIRECTOR_TOKEN must be exported before the next session; otherwise the director entry fails 401.
• A director-profile entry under another key (a url ending /mcp/director, or MCP_TOOL_PROFILE=director in its args or env): warn that claude --agent task-orchestrator:director will not see its tools, and offer to register it under the exact key.

Credential mode. The server is in credential mode when an unauthenticated POST <base>/mcp answers 401, or when the orchestration entry already carries an Authorization header:

curl -s -o /dev/null -w "%{http_code}" -X POST <base>/mcp

In credential mode each entry carries its own header, written exactly as the placeholders below, because Claude Code expands them from the environment. Never write a token into the file. The orchestration entry keeps the agents' token; the director entry gets a separate placeholder, with no nested default:

"headers": {"Authorization": "Bearer ${TASK_ORCHESTRATOR_API_TOKEN}"}

"headers": {"Authorization": "Bearer ${TASK_ORCHESTRATOR_DIRECTOR_TOKEN}"}

Tell the user to export both variables before starting Claude Code. The director token needs read, runs and decide and is a different token-file entry from the agents' token; the example token file, the kind choice and its hazard are in the "Director credential" block of `/task-orchestrator:configure-server`, which this step points to instead of repeating. Both entries load into every session, subagent and headless ralph iteration that reads the file with the variables set, so the separate token separates identity and audit, and authority only where TASK_ORCHESTRATOR_DIRECTOR_TOKEN is not exported (ralph, CI, workers). Never put kind: human on a token exported into a session that runs agents or subagents; answer human-only classes through REST POST /api/v1/ops/director/runs_write with the human token. Pointing both variables at one token loses the identity and audit split and puts decide (and with kind: human, the human-only classes) on the agents' own token, reaching every environment that exports it. In an environment that exports only TASK_ORCHESTRATOR_API_TOKEN, Claude Code still loads the file; the orchestration entry works, and the director entry shows a missing-variable warning in claude mcp list and fails 401 - the intended agent-only setup. A stdio server has no credential mode: its entry is local.

Who can answer what. On stdio, and on any unauthenticated or local server, every caller is the local agent principal (proof none), so human-only decision classes can never be answered there; director-or-human classes (run budget, attempt cap, deviation) can, through the director entry. A user who wants human sign-off needs bearer (or jwks) with a kind: human token.

Where to write. Edit <main>/.mcp.json only (read-modify-write, preserve everything else). When the orchestration entry lives elsewhere (user scope, ~/.claude.json), do not edit that file: print the director entry as JSON together with the command for the user to run, for example claude mcp add-json mcp-task-orchestrator-director '<entry json>' --scope user. Re-running is idempotent: an existing director entry is left alone and reported.

The entries take effect after the MCP servers reload (a new Claude Code session, or /mcp). The end report lists each entry, its file and its mode, and says how to use the director entry once the servers have reloaded: claude --agent task-orchestrator:director, or /task-orchestrator:director in a normal session.

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

{"tool": "items_read", "select": "list", "args": {"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 items_read overview. If roots exist other than the global containers (Session Retrospectives, Improvement Proposals, Retrospective Trends, 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.

Before the create, check that the server declares types at all. An undeclared type is rejected only when the declared set is non-empty; with no types declared the create succeeds schema-free, so the missing process-schema floor would go unnoticed. Read the server layer (config effective with no rootId; skip the check with a note if the config tool is not served):

{"tool": "config", "op": "effective", "args": {}}

If data.results[0].types is empty, tell the user the server has no process-schema floor mounted and point them to /task-orchestrator:configure-server before going on; create the anchor only if they choose to continue without it (it then has no project schema).

Name: from $ARGUMENTS, else the main checkout's directory name; confirm with the user. Create it at depth 0. A create takes type (see `items_write` create); the global floor declares project: