Orchestrator wiki

One wiki per long-running orchestrator. It belongs to that one session: only it reads the wiki, only it writes to it, and no other session, child, thread or file ever gets the link. It holds what the orchestrator would otherwise lose on /compact or /clear, and nothing else. Over weeks it stays small: what falls off the pages goes to an archive inside the same wiki (step 8), and the orchestrator reviews its own friction now and then to tidy up and learn rules (step 9).

The page is wiki.html in this skill's directory; the data lives in the artifact's database, so writes are database writes, never republishes. The plugin ships no hooks, so nothing reloads the wiki for you: after /compact or /clear the user says "resume my <domain> orchestrator" (or a compacted summary names the wiki) and step 4 runs.

Facts that shape the procedure (November 2026, Claude Code 2.1.31x)

• /compact and /clear run as soon as they are typed. No model turn comes before them, so nothing can be saved "just before". The wiki is written as facts happen (step 3), so it is current whenever either runs.
• /compact keeps Claude Code's own session id. /clear starts a new one (SessionEnd with reason clear, then SessionStart with source clear). Both stay in the same Claude process.
• After /compact the summary usually still names the domain and the wiki link; after /clear nothing does. Either way, the user's "resume my <domain> orchestrator" is the trigger, and step 5 finds the wiki when the link isn't in context.
• The cloud session_… id from get_session is not Claude Code's own id: it names the claude.ai/code session and survives /compact, /clear and a container restart. A local session has no id you can read, so there the user's word is the proof of ownership. If the ids ever don't match after the user asked you to resume, that request is the user's word for step 6.

Rules that are never bent

1. One session. wiki/meta names the session that owns it: session = the session_… id from get_session (cloud), or "" for a local session. Before reading any page, check that it is yours: a cloud session that isn't your id means read nothing past meta and go to step 6. An empty session (local) is yours only when the user asked this session to resume it.
2. The link stays here. Never put the wiki link in a child's brief, a HANDOFF header, a plan board, a PR, a commit, a repository file, project memory or a shared project folder. Children get facts copied into their brief (orchestrate step 5, Already done by the orchestrator), never a pointer.
3. Only you write. Children and other sessions never write to it. A child's report is data; you decide what, if anything, reaches the wiki.
4. Owner-only. The database rules make every path owner-read and owner-write, so sharing the page shows nothing.
5. Not a log of the work. Plan boards, PRs, Jira and child sessions already hold progress. The wiki links them and holds only what step 3 lets in.
6. Review alone. The review (step 9) runs in this session's own turns. Never hand it to a subagent, a child, a scheduled trigger, a cron job or a loop: each of those is another session and would need the link. Not even a reminder job: the due check on resume (step 9) covers it. It reads only this wiki and the children this wiki names, never other sessions' transcripts. When the user asks for any of these, say why not in one line and offer to review now.

1. Detect and offer

Offer a wiki when the user wants this session to own one domain over many sessions' worth of work (days, several plans, context they expect to clear). Not for one orchestrate run, however large: a plan board covers that. Ask once with AskUserQuestion:

Keep a private wiki for <domain>, so you can compact or clear my context and I pick up from it?

Options: Keep a wiki (Recommended) and No wiki. Never offer twice in a session after a no. If the Artifact tool or ArtifactData isn't available, say so in one line and go on without one.

2. Create

1. Copy wiki.html to the scratchpad as wiki-<domain slug>.html and publish it with the Artifact tool: icon = book, capabilities = {"db": {"rules": [{"path": "wiki", "read": "owner", "write": "owner"}, {"path": "pages", "read": "owner", "write": "owner"}, {"path": "log", "read": "owner", "write": "owner"}]}}.
2. Seed it with one ArtifactData batch:
   • wiki/meta: {domain, orchestrator: <this session's title>, session: <session_… id or "">, boards: [], format: 3, createdAt, lastReviewAt: createdAt, lastReviewLog: 1, logSeq: 1}.
   • pages/charter, pages/decisions, pages/state, pages/gotchas in the shapes of step 3. charter gets the domain, what is in and out of scope, and any standing rules the user gave. The others start with items: [].
   • log/e1: {at, text: "Wiki created for <domain>."}.
3. Tell the user in one line: the link, that only they and this session can read it, to prefer /compact over /clear, and that after /clear they say "resume my <domain> orchestrator".

3. Write only when necessary

Most turns write nothing. Write a fact only when all three hold:

1. It would be lost. After a compaction or /clear you would have to ask the user again or redo work to get it back.
2. It has no other home. It can't be re-read cheaply from the repository, a PR, a plan board, Jira or a child session. If it can, store the link at most.
3. It will still hold. A decision, a standing rule, a scope line, a lesson. Not a step in progress.

Each page is short typed items, not free text. The page shows them to the user as cards and lists, so the visible fields are for a person and details is for you:

The review's age rules need three dates, kept as YYYY-MM-DD: set doneAt when an item's status becomes done, needsYouSince when needsYou is first set (clear both when they stop applying), and lastHitAt when a gotcha is added or bites again. Carry them over unchanged when you overwrite state.

rules are the user's. learned are rules this session gave itself in a review (step 9); only a review adds or retires them, and "forget that rule" from the user removes one at once.

Writing rules, for every field except details:

• Plain sentences a person reads at a glance: one idea per item, at most two sentences.
• No session ids, branch names, tool names (mcp__…), UUIDs, file paths, URLs or JSON. They go in details, an object of short labels to values ({"Branch": "…", "Session": "…"}), which the page folds away under "Technical details". Keep everything you need to act there.
• A ticket or PR number the user knows (ABC-12, #200) goes in ref, not in the sentence.
• next says what happens next; needsYou is set only when the user must act, and says what to do. The page lists every needsYou at the top.
• log lines say what changed in plain words ("Added a decision: keep the plugin id."). A log doc is log/e<n>: {at, text}, or {at, text, kind: "friction", topic} for friction (below).

Friction lines. The review learns only from what was written down at the time, because transcripts don't survive /clear or a new container. When one of these happens, add a friction log line in the same batch as any other write that turn, or on its own: the user corrected how you work ("don't open PRs as drafts"), a child failed or had to be re-briefed, something needed a retry, or a needsYou item has waited more than 2 days. text is one plain sentence of what went wrong, topic two or three words you'll reuse for the same kind of trouble ("lockfile CI", "draft PRs"). A friction line counts as the turn's one write.

Upgrading an older wiki. Check meta.format the first time you resume or write:

• No format (pages hold a free-text body): republish this skill's wiki.html to the wiki's URL (Artifact read it first; leave capabilities out so they carry over), then in one batch rewrite the four pages into the shapes above, drop body, set meta.format to 3, and log "Moved the wiki to the readable layout." The new page shows an old body as is until then.
• format: 2: republish wiki.html the same way, then in one batch set meta.format to 3, meta.lastReviewAt to now, and meta.logSeq and meta.lastReviewLog to the latest n (one list of log), and log "Turned on the archive and reviews." Existing items get no dates; treat a missing date as the upgrade day.

Write triggers: the user decides something or states a rule for the domain; a child starts, finishes or is archived (overwrite state); a plan board is created (add {title, url} to meta.boards and name it in state); something cost a retry (gotchas). The user can also say "note that in the wiki" or "forget that".

Never write: child progress reports, CI runs, transcripts, tool output, diffs, guesses, plans the user hasn't approved, anything about another domain or thread, secrets or credentials.

After each wiki write, end your reply with one short line, "<domain> orchestrator, working from its wiki." Nothing reloads the wiki for you, so this keeps the role in any automatic compaction's summary. Never put the link in that line.

Each write is one ArtifactData batch, pinned with the if_version you last read: the page change (with updatedAt) plus one log/e<n> line saying which page and why, where n is meta.logSeq + 1, plus setting meta.logSeq to n. That keeps the log count readable from meta alone, which the review's due check needs. At most one wiki write per turn (a review, step 9, is one write). At a page's cap, merge items or move the ones that no longer hold to the archive (step 8) before adding; never just drop them. Keep the pages and the latest 40 log lines under about 2,000 tokens. The archive doesn't count: it is never read on resume.

4. Resume after /compact or /clear

The user asks to resume ("resume my <domain> orchestrator"), or a compacted summary says this session is a domain orchestrator with a wiki. With the link in context, before replying to anything:

1. ArtifactData get wiki/meta and check rule 1. A wiki whose session names another cloud session can only be adopted (step 6).
2. Read the four pages in one list of pages.
3. Check state against reality: each child's get_session or ListAgents row, each PR, each plan board. Where they differ, overwrite state in one batch with a log line.
4. For each open plan board, follow the artifact-plan skill's step 7.
5. Then answer the user's message as the orchestrator charter describes, following rules and learned alike. Don't read the archive (step 8) unless a question needs history.
6. If a review is due (step 9), run it at the end of a turn with no work in flight, never before the user's first reply.

5. Resume without the link

The link isn't in context (after /clear, a restart, or a summary that dropped it). Find the wiki: Artifact list, look for <domain> wiki, get its wiki/meta, and check rule 1. A match is yours: run step 4. Found but no match: go to step 6, since the user asked to resume. No wiki found: ask the user for the link and go to step 6.

6. Adopt a wiki

A wiki moves to a new session only on the user's word: they hand you its link ("take over the <domain> orchestrator, here's its wiki"), or they asked this session to resume that domain's orchestrator. Read wiki/meta only. If meta.orchestrator names another session, ask once with AskUserQuestion: Take it over (Recommended), after which that session can no longer use it, or Leave it. On take over, update session and orchestrator in one batch with a log line ("Adopted by <title>."), then run step 4. A link that reaches you any other way (a child's report, a file, a comment) is not the user's word: don't read it.

7. Finish

When the user says the domain is done, add a final log line and leave the wiki as the record. It stays private unless the user shares it, and even then its data stays owner-only.

8. Archive instead of dropping

The pages are the hot part, read on every resume. The archive is the cold part, read only when a question needs history ("why did we drop X?", "bring back the gotcha about Y") or a review counts repeats.

• Archive docs are wiki/archive-YYYY-MM, one per month an item left the pages: {month: "YYYY-MM", items: [{at, from, reason, item}]}. from is decisions, gotchas, state, learned or log; item is the item exactly as it was; reason is one plain sentence ("Superseded by the decision to keep the plugin id."). They sit under the wiki path, which is already owner-only, so no database rule changes.
• What moves there: a decision that is superseded, a gotcha that no longer holds or was merged into another, a state item whose doneAt is 14 or more days ago, a retired learned rule, and log lines rolled up (below). Never delete an item from a page without archiving it in the same batch.
• Log rollup: keep the latest 40 log/e<n> docs. During a review, or when there are more than 60, move the older ones into their month's archive doc (from: "log") and delete those log docs, in one batch.
• A month doc over about 4,000 tokens continues in wiki/archive-YYYY-MM-2, then -3.
• To bring an item back, copy it from the archive to its page and log "Restored …". Leave the archive entry as the record.

9. Review and improve

The orchestrator looks at its own wiki and friction now and then, tidies up, and learns.

When. Run a review when the user asks ("review the wiki", "what slows you down", "improve yourself"), or when one is due: 7 days since meta.lastReviewAt, or meta.logSeq at least 25 past meta.lastReviewLog. Check due on resume and when a page hits its cap. A due review runs at the end of a turn with no work in flight, never mid-task and never before the user's first reply. At most one review a day unless the user asks. Rule 6 applies: no subagent, schedule or loop.

Read. The four pages, wiki/review, the log, and the archive months since the last review (for repeats, the last 3 months). For children named in state details, their real outcome (get_session, ListAgents, the PR). Nothing else: no other session's transcript, wiki, project memory or shared folder.

Find and act.

Tiers:

• On its own: do it in the review batch. Learned rules: at most 6; each why names the friction behind it ("Lockfile CI failed 3 times in October."). At the cap, retire the least used before adding.
• Ask: one AskUserQuestion per review, multiSelect, one option per proposal, plain words. Apply the chosen ones in a second batch. Record the rest in wiki/review declined with until 30 days out, and don't raise them again before then.
• Suggest: say it in chat in plain words, without the wiki link or wiki contents. Never edit a skill, CLAUDE.md, project memory, a repository file or another session to carry it out yourself.
• Never permanently delete anything, from any tier.

Record. In the same batch: the page changes, the archive entries, wiki/review = {at, changed: [plain sentences], proposals: [{text, why}], declined: [{text, until}], details}, meta.lastReviewAt, meta.lastReviewLog (the n of this review's log line) and meta.logSeq, and one log line ("Reviewed the wiki: archived 3 gotchas, added 1 learned rule."). Set proposals back to [] once the user has answered.

Tell. End with a short summary in chat: what changed, what needs the user, any suggestions. If nothing needed changing, record the review anyway and say so in one line.