swcstudiospace/claude-ultrathink/ultrathink-kickoff

ultrathink-kickoff

You were told to invoke this skill with stateFile=<path> (on Hermes it loads with skill_view name="ultrathink:ultrathink-kickoff"; plugin skills load as ultrathink:<name>). Follow these steps in order. Tracking must be real (rows exist, links resolve) in every configured tracker before you start engineering work.

0. Read the state

Read the JSON file at stateFile. It is a SessionRecord:

interface IssueRef { id: string; identifier: string; url: string; title: string }
interface SessionRecord {
	sessionId: string;
	engine?: string;
	host?: string;
	result: { xml: string; original: string; root: string; source: "llm" | "fallback" };
	graph?: { goal: string; nodes: Array<{ id: string; title: string; kind: string; question: string; dependsOn: string[]; thinking?: string; conclusion?: string }> };
	clarifications?: Array<{ id: string; question: string; header: string; why: string; options: Array<{ label: string; description?: string }>; default?: string; blocking: boolean; answer?: string }>;
	plan?: {
		graphId: string;
		task: { graphId: string; item: string; description: string; upliftedPrompt: string; agent: string; status: string; linearState: string; repo?: string; branch?: string };
		issues: Array<{ graphId: string; nodeId: string; item: string; thought: string }>;
		subIssues: Array<{ graphId: string; nodeId: string; item: string; step: number; thought: string }>; // several per nodeId — one per rationale step
		linearIssues: Array<{ nodeId: string; title: string; description: string }>;
		linearSubIssues: Array<{ nodeId: string; step: number; title: string; description: string }>;
		hitl: { blocking: Array<Clarification>; nonBlocking: Array<Clarification> };
	};
	tracking?: {
		graphId: string;
		status: "complete" | "partial" | "failed";
		linearTeam?: string;
		linear: { nodes: Record<string, IssueRef>; steps: Record<string, IssueRef> }; // steps keyed "<nodeId>.<step>"
		notion: { taskUrl?: string; nodes: Record<string, string>; steps: Record<string, string> };
		errors: string[];
		updatedAt: number;
	};
}

The spec file is the same path with .xml instead of .json (sessions/<id>.xml); the prompt context also names it as the spec path.

If plan is missing (the planner fell back to boilerplate), take the no-plan path: skip steps 1–3 (no rows to finish, nothing to register), resolve clarifications in step 4 from record.clarifications, then step 5 with the spec file (or result.xml) as the final prompt — do not block on tracking. This is the fail-open path.

1. Finish tracking

Rows go to the Notion data source notion.dataSourceUrl (a collection://… URL) and the Linear team linear.team from the ultrathink config: ~/.config/ultrathink/config.json, ~/.claude/ultrathink.json and <project>/.claude/ultrathink.json, later files winning. <repo>/bin/ultrathink status, run from the project directory, prints both as Notion: … and Linear team: … (not configured when unset); <repo> is the plugin root (this file is <repo>/skills/ultrathink-kickoff/SKILL.md). Skip a tracker that is not configured silently: create nothing in it and do not mention it. If the user asks to set up Notion tracking, <repo>/bin/ultrathink-mcp notion init --parent <page url or id> --write-config creates the database and saves its notion.dataSourceUrl to ~/.config/ultrathink/config.json.

• If tracking.status is "complete": every row exists in each configured tracker. Skip all row creation and go to step 3.
• Otherwise — tracking is absent (on Hermes the planner creates no rows, so it always is on the first run) or not complete — and the state file has a plan, run the command printed in the prompt's Ultrathink tracking section once with the shell tool (without a plan there are no rows to finish: skip to step 4, reading record.clarifications):

``sh <repo>/bin/ultrathink-mcp track complete --state <stateFile> ``

It creates only the missing Linear/Notion rows through the shared MCP gateway (reusing the host's stored OAuth logins), updates tracking in the state file, rewrites the spec's <ISSUES> block and prints the Linked-issues TODO lines. Re-read the state file afterwards. If it reports that tracking is not configured or turned off, go to step 3 without mentioning it. If it reports notion: login required, tell the user to run <repo>/bin/ultrathink-mcp auth login notion and continue — do not block.

• Fail open when a tracker fails. If the command reports that Notion or Linear is down, unreachable, rate-limited, unauthorised or returned errors (! … lines, tracking partial or tracking failed), do not create rows by hand: tell the user in one line which tracker failed and continue to step 3.
• Only if the command itself cannot run (the bin/ultrathink-mcp file is missing, bun is missing, or the shell exits 127 or 126), do step 2 manually — never because a tracker is down.

2. Manual fallback (only when step 1's command could not run)

Create only what tracking does not already contain. This step needs the Notion and Linear MCP tools in this session; if a tracker's tools are not available, tell the user once to register them with bun <repo>/scripts/mcp-register.ts (or connect the official Notion/Linear MCP servers), skip that tracker and continue — never block the work.

Linear (team = tracking.linearTeam, else the configured linear.team; skip Linear when neither is set):

1. Look up existing issues first: list_issues with query = ultrathink graph <plan.graphId>. Every issue the planner creates ends its description with the footer ultrathink graph <graphId> · node <nodeId> (plus · step <n> for sub-issues); reuse matches instead of creating duplicates.
2. For each plan.linearIssues entry without a ref, in dependency order: save_issue with team, title, description (keep the footer), and blockedBy = identifiers of the node's dependsOn issues.
3. For each plan.linearSubIssues entry without a ref: save_issue with team, title, description, parentId = the node issue's identifier. Batch independent creates; if one fails, still create the rest and report which nodeId/step failed.

Notion (data source = the configured notion.dataSourceUrl; skip Notion when it is not set): notion-fetch the data source once for the schema and send only properties that exist. Find existing rows by Graph ID = plan.graphId (query tool SQL mode: SELECT url, "Level", "Item" FROM "<data-source-url>" WHERE "Graph ID" = ?). Then create with notion-create-pages:

• Task row: Item, Level=Task, Description, Uplifted Prompt, Agent (= plan.task.agent; if the select rejects it, omit it — never substitute claude-code), Status, Linear State, Repo, Branch, Graph ID.
• Issue rows (one per node): Item, Level=Issue, Thought, Parent Item = Task page, Graph ID, Linear URL, Issue ID.
• Sub-Issue rows (one per rationale step — never collapse steps): Item, Level=Sub-Issue, Step, Thought, Parent Item = that node's Issue page, Graph ID, Linear URL, Issue ID.

Keep every identifier/URL you created; steps 3 and 5 use them.

3. Optional: register the graph with an Agent Substrate server

This is an optional integration. Run it only when an MCP server named substrate is connected in this session and you have its graph_register tool; otherwise skip this step silently — do not log, mention or suggest it. When it is connected, call graph_register on it. It is idempotent by graph_id, so call it without checking for an earlier registration. On Cursor the session record's host is cursor; pass that as surface (the same rule as every other host: claude-code only when host is absent). Build it from the tracking refs, leaving out fields whose value is absent:

Fail open. If the call errors, log one line and continue. Do not retry or ask the user.

4. Resolve HITL clarifications

Without a plan, read record.clarifications instead of plan.hitl: blocking questions are those with blocking: true and no answer, non-blocking those with blocking: false and no answer (already-answered items stay answered).

• For every item in plan.hitl.nonBlocking: proceed with its default option and state the assumption plainly in your next message (do not ask about it).
• For every item in plan.hitl.blocking (at most 4, already deduplicated): call the host's question tool once (AskUserQuestion in Claude Code, ask in Omp, clarify in Hermes), passing all of them together — each with its header, question, and options (the option matching default first). If no question tool is available, proceed with every blocking default and say so.
• On Hermes, that one call is clarify with {"questions": [{"question": "<header>: <question>", "choices": ["<default label>", "<other option label>", …]}]} — at most 4 choices per question with the default first (Hermes labels the first choice Recommended and adds Other itself) and at most 5 questions. If an answer says no user is available (Hermes -q/-z modes) or the tool errors, proceed with every blocking default and say so.
• Persist the user's answers into the spec before anything reads it (step 5 and any Cursor handoff): in sessions/<id>.xml, add <ANSWER source="user">…</ANSWER> (answer text XML-escaped) inside the <CLARIFICATION> of the question it answers, after </OPTIONS>. The <CLARIFICATIONS> block already holds one <CLARIFICATION> per blocking question. Replace an existing <ANSWER> rather than adding a second. If the block has no entry for a question, append one in the same format. An answer kept only in chat never reaches the spec, so the orchestrator would build the default instead. Stated assumptions need no entry: the default option already carries recommended="true".

5. Set Implementing and emit the final prompt

When the plan carries the Cursor swarm note (## Cursor swarm), do steps 1 and 4 only, then stop. The Cursor session hands the unit to a01-orchestrator, so do not emit the final prompt in steps 2 and 3 here.

1. Set the Task Status to "Implementing": notion-update-page on tracking.notion.taskUrl when present (skip silently when absent). If the Notion MCP tools are not available in this session, tell the user once to register them with bun <repo>/scripts/mcp-register.ts (or connect the official Notion MCP server), skip this update and continue — never block the work.
2. The final prompt is the full spec file (sessions/<id>.xml, the spec path from the prompt context), which already carries the <ISSUES> block with identifiers and URLs. Do not use plan.task.upliftedPrompt — that copy is truncated to 1900 characters.
3. Copy every Linked issues TODO line into the host TODO tool verbatim, keeping the identifier and URL on each line. When step 1 ran track complete, take the lines from its output — the prompt-context lines are stale then (they still show (pending) rows); otherwise take them from the prompt context (without a plan there are none — skip).
4. Mark the session kicked off, once: <repo>/bin/ultrathink-mcp session mark --state <stateFile> kicked-off. Fail open: if it errors, ignore it and continue.

6. Proceed as normal