Compare commits

..
Author SHA1 Message Date
Matt PocockandClaude Opus 4.8 a12cca62fa wayfinder: use placeholders in Handoff example, drop no-op
Cut the "(trailing name orients you; it's ignored on paste)" gloss —
a # comment is self-evident. Replace the arbitrary "Briefing pipeline"
map name and specific ticket names with <map name>/<ticket name>
placeholders, consistent with the surrounding <map-url>/<issue-url>
style so nothing reads as a real referent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:28:42 +01:00
Matt PocockandClaude Opus 4.8 eb63f6e92c wayfinder: dedup identity claim in Refer-by-name
"id stays the identity" duplicated the Tickets section's "issue id is
its identity" — single source of truth belongs there (co-located with
the wiring/blocking mechanics that depend on ids). Reword to state the
pasteable-handle exception (link target, Handoff URL) without
re-defining identity. Trim redundant rationale wording.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:26:41 +01:00
Matt PocockandClaude Opus 4.8 ee014fa8b1 wayfinder: refer to maps and tickets by name, not id
Add a "Refer by name" convention so Wayfinder surfaces maps and
tickets by their human-friendly title in everything the human reads
(narration, Decisions-so-far, Handoff) rather than bare ids, numbers,
or slugs — a wall of #42, #43, #44 is illegible; names read at a
glance. The id/URL stays the identity and pasteable handle, riding
inside the name's link.

Update the Handoff example to demonstrate it: name the map in the
header and annotate each parallel command with its ticket name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:23:55 +01:00
3 changed files with 8 additions and 23 deletions
-1
View File
@@ -8,4 +8,3 @@ Skills that are still being developed. They're not ready to ship — expect roug
- **[writing-beats](./writing-beats/SKILL.md)** — Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end.
- **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article.
- **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step.
- **[claude-handoff](./claude-handoff/SKILL.md)** — Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked.
@@ -1,18 +0,0 @@
---
name: claude-handoff
description: Hand the current conversation off to a fresh background agent that picks up the work immediately.
argument-hint: "What will the next session be used for?"
disable-model-invocation: true
---
Write a handoff summary of the current conversation so a fresh agent can continue the work. Instead of saving it, launch a background agent seeded with the summary as its prompt: `claude --bg --name "<descriptive name>" "<handoff summary>"`. It starts in the current working directory and returns immediately; the user manages it with `claude agents`.
Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"`) — it sets the display name shown in the job list, session picker, and terminal title.
Include a "suggested skills" section in the summary, which suggests skills that the agent should invoke.
Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
Redact any sensitive information, such as API keys, passwords, or personally identifiable information — the summary becomes the agent's prompt.
If the user passed arguments, treat them as a description of what the next session will focus on and tailor the summary accordingly.
+8 -4
View File
@@ -5,6 +5,10 @@ description: Chart a route through a foggy problem — turn a loose idea into a
A loose idea has arrived — too big for one agent session, and wrapped in fog: the route from here to a plan isn't visible yet. This skill charts it as a **shared map** on the repo's issue tracker, then works its tickets one at a time. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
## Refer by name
Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far, the Handoff — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link, and Handoff commands still paste the URL — but they ride *inside* the name, never stand in for it.
## The Map
The map is a single issue on this repo's issue tracker, labelled `wayfinder:map` — the canonical artifact. Its tickets are child issues of the map.
@@ -104,7 +108,7 @@ End every session with a **Next steps** block the user can copy-paste. Two cases
**Open tickets remain.** Query the map for the currently-unblocked children, then give two copy-paste options: a bare command for one session (you pick the next ticket), and one pinned command per unblocked ticket for running them in parallel. Paste one line per fresh window — opening one, some, or all of them.
> **Next steps** — 3 tickets unblocked. Clear the context, then open fresh sessions.
> **Next steps** — *<map name>*: 3 tickets unblocked. Clear the context, then open fresh sessions.
>
> **One session** — resolves the next unblocked ticket:
>
@@ -115,9 +119,9 @@ End every session with a **Next steps** block the user can copy-paste. Two cases
> **Parallel** — paste one line per window, up to all 3:
>
> ```
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>.
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>.
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>.
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>. # <ticket name>
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>. # <ticket name>
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>. # <ticket name>
> ```
**No open tickets remain.** The fog is pushed back far enough that the way to the goal is clear — the map is done. (The initial grilling may also surface no fog at all, in which case there was never a map to chart.) Recommend implementing directly, or using `/to-prd` to schedule a multi-session implementation.