Persona at invocation

Before conversational narration, read Persona: and Style: in the active project's ## Agent skills block from CLAUDE.md or AGENTS.md. Prefer the file containing the block, then an existing file; ties use CLAUDE.md. A symlink pair is one file. Read the saved value anew on each invocation, including from a subdirectory using the project root. No accessible project or no line means ordinary behavior. Do not search another project or global settings for this preference.

During the Persona at invocation stage, archmage on either line loads this skill's own references/archmage.md for the active workflow. off or an absent value leaves ordinary behavior active. An unknown value leaves ordinary behavior active and gets a brief explanation when conversational output is allowed; it does not stop the work. Explicit conversation instructions override the saved voice without writing settings. A request to enable Archmage for this workflow also loads the local reference.

Apply the voice only to lead-agent conversation. Deliverables, specialist roles, reply-only responses, and JSON-only output retain their contracts, with no added narration. End the persona with this workflow unless the user requests otherwise or a Style: line names archmage, which keeps the voice on for the whole session.

Scry

Honor the user's explicit instructions and decisions already made in this conversation over this skill's workflow defaults. A rule this file states with never, or as read-only, is a gate: it holds whatever the conversation says, and an instruction to cross one is declined and reported. Continue authorized work; ask only about unresolved choices that would materially change the result. Preparing or reviewing work does not authorize publishing it.

If a skill rule requires a pause or leaves requested work unfinished, name and link to the exact SKILL.md and quote the rule. Then explain what decision or prerequisite is missing. Distinguish a required gate from your interpretation.

A loose idea has arrived, too big for one session. The way to the destination is still fog. This skill charts that way as a shared map on GitHub, then works decision tickets (questions whose answer is a decision) one at a time until the route is clear.

The destination is named first. It might be a spec, a locked decision, or a change made in place. Name it, because every ticket hangs off it.

Operating principles

• Decisions, then delivery. Each ticket resolves a question. The map is done when nothing is left to decide before someone goes and builds. The pull to start building is the signal the map is finished. An effort can override this in its Notes.
• One ticket per session, except research tickets created while charting, which resolve in parallel in that same session.
• Refer by name. Every map and ticket is an issue with a title. In anything the human reads, use that title. Wrap the link inside the name. A wall of #42, #43 is illegible.
• Claim before work. Assign the ticket to the person driving this session first, so a parallel session skips it. An open unassigned ticket is unclaimed.
• The map is an index. A decision lives on its ticket. The map gists it and links. It does not restate the answer.

<SKILL_DIR> is the absolute directory this SKILL.md lives in. Substitute the real path every time it appears. Do not assign it to a shell variable first: a sandboxed or worktree-isolated session refuses bash "$VAR/script.sh" because it cannot resolve the path to read the script.

Arguments

Parse tokens, then treat the remainder as the idea, number, or URL.

No number or URL (a loose idea). Chart a new map.

A number or issue URL. Load that issue.

• Label scry:map: walk that map.
• Label scry:research, scry:prototype, scry:grilling, or scry:task: walk its parent map and claim this ticket.
• The same labels under the older wayfinder: prefix mean the same thing. Walk them as they are; do not relabel.
• Any other issue: chart a new map whose destination is informed by that issue.

Execution spine

1. Resolve the tracker (Stage 1).
2. Decide chart vs walk from the arguments (above).
3. Chart: Stage 2, then stop. Walking tickets is a later session.
4. Walk: Stage 3. Check for an already finished map, or resolve one ticket and file new fog. Check closeout before stopping.

Stage 1: Tracker

If docs/agents/issue-tracker.md exists, read it. Its Tracker: line names the tracker. On github, follow its "Wayfinding operations" section for any mechanic it specifies (extra labels, owning docs, parent-link fallbacks) and continue below. On any other tracker, that section replaces map.sh entirely: it says what a map, a ticket, a blocking edge, a claim, and a resolution are there, and which connector or API to use. Follow it for every operation in Stage 2 and Stage 3, keep the same map body and ticket shapes from references/map-shape.md, and skip the rest of this stage. When it says maps are not supported, read references/scratch.md and keep the map under .scratch/. Missing file: GitHub via gh, using the operations in references/github-ops.md.

Load references/github-ops.md now. scripts/map.sh is the only way to create issues, attach children, wire blocks, query the frontier, and claim. Do not improvise those gh calls.

Confirm the host with gh repo view. If that fails, stop.

Pass GH_HOST=<host> inline on every map.sh invocation. Derive the host from gh repo view --json url --jq .url, or from the issue URL if one was passed. Shell state does not persist between Bash calls. On github.com the prefix can be dropped.

Ensure labels exist once per session:

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" ensure-labels

Exit 3 from the script means this token cannot write issues (usually HTTP 403). Read references/scratch.md and follow it. Do not keep retrying gh issue create.

Stage 2: Chart

Load references/map-shape.md, references/grilling.md, and references/domain.md.

2a. Name the destination

Grill until the destination is a sentence or two: the spec, decision, or in-place change this map is finding its way to. Update CONTEXT.md and ADRs as terms land.

The destination fixes the scope. Work past it belongs in Out of scope on the map, never in the ticket list.

2b. Map the frontier

Grill again, breadth-first this time: fan across the space rather than deep on one thread. Surface the open decisions and the first steps takeable now.

If this surfaces no fog (the way is already clear, and the whole journey fits one session), you do not need a map. Stop and ask how they want to proceed.

2c. Write the map

Create the map issue, label scry:map. Destination and Notes filled in. Decisions so far empty. Fog sketched into Not yet specified.

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" create-map "Map: <destination in a few words>" <<'EOF'
<body from references/map-shape.md>
EOF

Notes record: domain; files every session should read; standing preferences; any owning doc that later resolutions should update (a decision log, a spec).

2d. File the tickets you can specify

A ticket is ready to file when you can state its Question precisely. Sharpness of the question matters. Whether you can answer it yet does not.

Create each one as a child of the map, labelled scry:<type> (research, prototype, grilling, task). See Ticket types in references/map-shape.md.

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" create-ticket MAP_NUMBER TYPE "Title" <<'EOF'
## Question

<the decision or investigation>
EOF

Wire blocking edges in a second pass, once every ticket has a number:

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" wire CHILD_NUMBER BLOCKER_NUMBER

Everything still too dim to phrase stays in Not yet specified. Do not pre-slice fog into ticket-sized pieces.

2e. Fire research

For each research ticket just created, read references/research.md and spawn a generic subagent seeded with that file plus the ticket's Question. They run as one concurrent batch. Charting hand-resolves nothing else.

After recording the research results, run Stage 3f's closeout check. Stop. Charting is one session.

Stage 3: Walk

Load references/map-shape.md if you have not this session.

3a. Load the map

Fetch the map issue (the low-resolution view). Do not fetch every child body yet.

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" view MAP_NUMBER
GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" frontier MAP_NUMBER

Orient to Destination and Notes before picking a ticket.

If the map is already closed, report that and stop without another completion note. Otherwise run Stage 3f's closeout check before choosing work. If the map is finished, close it and stop. If the frontier is empty but the map remains unfinished, report what keeps it open: assigned or blocked tickets, unresolved fog, or an unmet destination. Specify remaining in-scope questions where possible; ask only about choices the available decisions do not settle. If no ticket can be worked, stop after reporting the remaining work.

3b. Choose and claim

If the user named a ticket, use it. Otherwise take the first frontier row (open, unblocked, unclaimed, map order).

Claim it before any work:

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" claim TICKET_NUMBER

3c. Resolve

Fetch that ticket's body. Zoom into a related or closed ticket only when this question needs it.

Load the reference for its type, and only that type:

If Notes name more files to read, read them. When the type is unclear, load grilling and domain.

you-pick (or the user saying "make the decisions") accepts recommended grilling answers.

3d. Record

Post the answer as a comment, close the ticket, append one gist line to the map's Decisions so far.

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" comment TICKET_NUMBER <<'EOF'
<answer>

Docs impact: <owning doc and what changes, or none>
EOF
GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" close TICKET_NUMBER

Then view the map, splice a line under Decisions so far, and update-body the map:

- [<ticket title>](<url>): <one-line gist>

If Notes or the repo name an owning document, write the decision there too. The ticket still holds the full answer.

Assets created while resolving (research notes, a prototype path) are linked from the comment. Do not paste them into the map.

3e. Graduate fog

Create-then-wire any question the answer just made specifiable. Clear each graduated patch from Not yet specified so it lives only as its new ticket.

If this answer shows a ticket sits past the destination, close that ticket and move one line into Out of scope (gist, why, link). It does not go in Decisions so far.

If the decision invalidates other tickets, update or close them.

Run the closeout check below, then stop. Closing the parent finishes this session and does not count as working another ticket.

3f. Close out the map

Re-read the map and check all children, including assigned or blocked tickets. On GitHub:

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" view MAP_NUMBER
GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" children MAP_NUMBER

On GitHub, before reviewing or deriving the replacement, save the original body in a private temporary file. The body read must remove a partial snapshot and abort on failure:

snapshot_path=$(mktemp)
if ! GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" body MAP_NUMBER > "$snapshot_path"; then
  rm -f "$snapshot_path"
  exit 1
fi
printf 'original_body=%s\n' "$snapshot_path"

An empty frontier or a full child progress count alone does not establish completion. Every child must be closed. Review Not yet specified against the recorded decisions: clear resolved fog, move work beyond the destination to Out of scope with a reason, and keep any unresolved in-scope question visible. Verify that Destination is reached under the map's Notes, and that required owning documents contain the decisions. Read individual resolutions when the gists do not establish this. Closed tickets that were invalidated or ruled out do not by themselves prove the destination was reached.

If anything remains, keep the map open and tell the user what remains. Do not start building merely to close a decision map. If nothing remains, preserve the other sections and prepare any cleanup and a brief Completion section stating how the destination was reached and linking any resulting spec or owning document. Update an existing completion note when retrying after a failed close.

Shell variables do not persist between calls. Record the printed absolute path, then set original_body to that exact path in the update call below. Read the body and prepare the replacement from that snapshot. Write it with the guard, and stop without running close-map if the snapshot is missing, the read fails, or the current body differs:

original_body='<recorded absolute snapshot path>'
if ! GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" update-body MAP_NUMBER --expected-body "$original_body" <<'EOF'
<updated body>
EOF
then
  rm -f "$original_body"
  exit 1
fi
rm -f "$original_body"

The guard detects stale snapshots between the read and comparison. It cannot eliminate the residual read/write race between comparison and the GitHub write, since those calls are not an atomic compare-and-swap.

GH_HOST=<derived-host> bash "<SKILL_DIR>/scripts/map.sh" close-map MAP_NUMBER

close-map rechecks child states before closing; the agent owns the destination and fog checks above. If a read fails or a child remains open, report the reason and leave the map open. Confirm the final state with view before reporting it closed.

On another tracker, apply the same checks through its Wayfinding operations and close the parent using that tracker. For a scratch map, check every linked ticket file, append the completion note to the map, and set its Status: closed. A map already closed needs no further write.

References