Wayfinder is the heaviest, most cognitively demanding flow, and the
wiki shows people misusing it two ways: over-reaching for it on
well-scoped work (it's slower and denser than a single grill), and
losing the way at the handoff after the map (looping straight into
/implement and skipping /to-spec). Sharpen the router's wayfinder
on-ramp to steer both.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rule 4 is about skipping polish, not the prototype's fate; the trailing
"then let it go" was a leftover from the old delete-it framing and now
misreads as discard, contradicting capture-as-primary-source. Cut it,
and rename LOGIC step 7 off "let go".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The depth-based rules already treat any subfolder as private, so the
config needs no change. Document lib/ (implementation) and tests/ as the
conventional two-folder shape, with entry points at the root — a fixed
convention that never needs the config extended for a new folder.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Rename skill to setup-ts-deep-modules (it's TypeScript-specific).
- A package's public surface is now its ENTRY POINTS — every file at the
package root — not one designated index.ts. Implementation lives in
subfolders and is private. This is depth-based and extension-agnostic.
- Packages can expose several small entry points instead of funnelling
everything through one giant barrel index; barrels are discouraged, and
the generated repo docs (step 7) say so explicitly.
- Rules renamed accordingly: entrypoint-boundary-from-app,
entrypoint-boundary-across-packages, tests-through-entrypoints.
- Example package now hides impl in a lib/ subfolder.
Re-validated against dependency-cruiser 16: multiple entry points and
cross-package entry imports pass; deep imports into subfolders fail with
the expected rule from app code, other packages, and tests.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Step 7 now writes <packages-root>/README.md next to the packages it
governs, and adds a context pointer from CLAUDE.md/AGENTS.md so an agent
discovers the boundary rule.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The install location isn't known at runtime, so a relative path breaks.
Use the literal skill invocation instead.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The "keep it as a primary source" section restated rule 6 and was
padded with no-ops. Fold the one extra bit (capture the answer) into
rule 6 and delete the section: capture the prototype as a primary
source on a throwaway branch, pointer on the issue.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A user-invoked setup skill that wires dependency-cruiser into a
TypeScript repo so each package under the packages root is a deep
module: everything hidden behind its `index.ts` interface.
Ships a `.dependency-cruiser.cjs` template with four error-level rules —
index boundary from app code, index boundary across packages (with
intra-package freedom via $1 back-references), tests-through-the-index,
and no-circular — plus a commented layering stub. The skill installs the
tool, folds a `lint:boundaries` script into the repo's umbrella check,
scaffolds an example package, and self-verifies that a deep import fails.
Rules validated against a live dependency-cruiser 16 run.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The final line of to-tickets/SKILL.md carried a stray `</content>`
closing tag with no matching opening tag — a packaging/serialization
artifact from the planning-skills refactor (386d4ff), not valid skill
content. The same stray tag had leaked into the generated landing
docs for to-tickets and to-spec. Strip it from all three.
Fixes#495
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reframe the artifact handling as capturing the prototype somewhere out
of main — a throwaway branch — with a context pointer to it left on the
implementation issue, instead of "disposing" of it. The main branch
still keeps only the validated decision.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework /setup-matt-pocock-skills to ask fewer, friendlier questions and
align the local-markdown issue tracker with the current spec.
- Triage labels: asked only when the `triage` skill is installed, and then
as a single recommended-yes question ("keep the default triage labels?")
instead of an override interrogation. When triage isn't installed, the
section and docs/agents/triage-labels.md are skipped.
- External PRs as a request surface: no longer a setup question. The
GitHub/GitLab templates still carry the flag, defaulted off; flip it in
docs/agents/issue-tracker.md later.
- Domain docs: default to single-context without asking; multi-context is
only offered when the repo shows monorepo signals.
- Local-markdown tickets: one file per ticket under
.scratch/<feature>/issues/<NN>-<slug>.md, never a single combined
tickets.md. /to-tickets, ask-matt, and the local template now agree, and
the spec file is spec.md (not PRD.md) to match /to-spec.
- Re-sync docs pages for setup-matt-pocock-skills and to-tickets; changeset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the secondary-source label — the actionable distinction is just
that the prototype is a primary source to retain on a throwaway branch.
Collapse the re-descriptions in LOGIC/UI so they point to SKILL for the
disposal concept and add only branch-specific nuance.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Retain the prototype as a primary source on a throwaway branch linked
from the relevant issue, rather than deleting it, while the distilled
answer remains the secondary source. Keeps prototype scaffolding out of
the main branch without destroying the runnable evidence.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
implement is the central Main Flow step but was missing from the
public Reference list. Add it after to-tickets.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The grill-led idea→ship chain stays the documented front door; wayfinder
is a situational on-ramp (greenfield / huge feature build), reserving
"new default spine" for a potential v2.
- ask-matt router: name wayfinder's concrete triggers
- grill-me / grill-with-docs: signpost up to wayfinder as the
too-big-for-one-session on-ramp
Resolves the main-flow decision on the Skills v1.1 wayfinder map (#120).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Graduate `wayfinder` out of in-progress into the engineering bucket
(plugin.json, top-level + Engineering READMEs under User-invoked, docs
page, ask-matt on-ramp, disable-model-invocation).
Consolidate the 22 pending changesets into 10 coherent v1.1 entries:
one `wayfinder` (rename from decision-mapping + full reframe +
graduation), one `grilling`, one `code-review`, one `tdd`; fold the
superseded to-issues changeset into unify-to-tickets and drop its stray
`</content>` tag. Highest bump is minor → 1.0.1 becomes 1.1.0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
It documented what the skill does rather than steering the agent — the
publish mechanics it described are already Step 5's instructions, and the
conceptual framing already lives in ask-matt and the docs page.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Executes the `unify-to-tickets` decision (personal-wiki #23), reworking
this PR from "add /to-plan" into the full planning-skills unification.
- Rename /to-prd → /to-spec. "spec" is now the single through-line term
(the skill still opens with "you may know this document as a PRD" for
discoverability).
- Merge /to-plan + /to-issues into one /to-tickets skill; delete
/to-issues. /to-tickets emits a set of tickets, each declaring its
blocking edges — one medium-agnostic artifact that reads as a
sequential plan (local `tickets.md`, edges as text) or a parallelizable
DAG (real tracker, native blocking links). The edges live in the ticket
either way; the medium only decides whether anything acts on them in
parallel.
- ask-matt now routes idea → /to-spec → /to-tickets → /implement.
- Sweep every cross-reference (docs pages, chain diagrams, CONTEXT.md,
ADRs, .agents, setup templates) to the new names and vocabulary.
- Rewrite the changeset to describe the unification.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fold the redundant 'thin vertical slice cuts through all layers, NOT
horizontal' intro sentence into vertical-slice-rules bullet 1 (it was
duplicating the bullet), and cut to-plan's 'no parallelism / top-to-bottom'
restatement — 'sequential' is already anchored as the leading word. Keeps
the shared core identical across the two sibling skills.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a user-invoked `to-plan` skill — the sequential, HITL sibling of
`to-issues`. Both slice work into tracer-bullet vertical slices, but
`to-plan` produces one ordered sequence you drive by hand, one phase per
fresh context, rather than parallel independently-grabbable issues.
It publishes to the tracker `/setup-matt-pocock-skills` configured, shaped
to it: a single sequential `plan.md` for a local tracker, or a parent
issue with ordered sub-issues (native sub-issues where supported) for a
real one.
Registers the skill everywhere CLAUDE.md requires (plugin.json, top-level
and bucket READMEs, docs page), updates the `ask-matt` router's main-flow
fork to offer both to-issues and to-plan, and adds a changeset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wayfinder pinned the literal docs/agents/issue-tracker.md, breaking the
indirection to-issues/to-prd/triage rely on: they resolve the tracker
through the ### Issue tracker block setup writes into CLAUDE.md / AGENTS.md.
In repos that keep agent docs elsewhere, wayfinder silently fell back to
local-markdown. It now follows the same pointer and reads the doc's
"Wayfinding operations" section by name.
Closes#471
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Revert the description change and keep the wide-refactor material in
one place. Reshape the skill into a lean Process (steps) and a
Reference section holding the vertical-slice rules, the wide-refactor
expand–contract rules, and the issue body template as co-located
blocks the steps point to.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a wide-refactor exception to the tracer-bullet rule: a single
mechanical change whose blast radius fans across the codebase can't
land as one green vertical slice. Seed "wide refactor" / "blast radius"
across the description, the explore step (detection), and the drafting
step (strategy), and give the expand–contract sequence in prose.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Students reported /wayfinder picking a grilling ticket and grilling
itself instead of turning to the human (confirmed by @_noshit /
@maudova; Matt: "that sounds like a bug"). Root cause: a grilling line
written for the live-human case ("explore the codebase instead") reads
as license to answer questions autonomously once wayfinder runs it in a
resolve-the-ticket frame.
Fix with affirmative framing (no negative-space "don't"):
- grilling: split facts (look up) from decisions (put to the human, wait)
- wayfinder Grilling ticket type: a back-and-forth with the human, who
answers each question
- wayfinder Invocation: grilling always runs with the human in the loop
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Negative Space read as clever but not actionable — "notice your
silences" is fuzzy legwork the agent can't reliably act on. Negation
stays: a checkable authoring failure with a positive-instruction cure.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two adjacent Steering failure modes about how language you think of as
"off" still steers:
- Negation — a prohibition names the forbidden behaviour and makes it
more available, not less (don't-think-of-an-elephant). Cure: prompt
the positive.
- Negative Space — what you omit is delegated to the agent's priors,
not left neutral. Cure: read a draft for what it's silent on and
decide each omission deliberately.
Each carried as a full GLOSSARY entry plus a SKILL.md failure-mode
bullet, matching every other failure mode.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Address review: don't preclude execution. Wayfinder is planning by
default, but an effort's Notes can carry execution into the map. Collapse
the section to one paragraph, revert the destination sentence to its
original (which already allowed an executed change), and drop the Task
cross-reference to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a "Plan, don't do" section as the single source of truth for the
plan/execute boundary, and bring two passages into line with it:
- Destination is always a set of resolved decisions, never the executed
change itself (the migration example previously read as execution).
- The Task ticket type now earns its place only by unblocking a decision,
pointing back to the new section rather than restating the principle.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Not "implement directly" — the point is the journey fits one session and
doesn't justify a map. Stop and ask the user how to proceed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bring back the "skip the map when there's no fog" branch that was
collateral-deleted with the Handoff section. Co-located in Chart the
map step 2, where the fog/no-fog outcome is determined: if breadth-first
grilling surfaces no fog, offer to skip the map and implement directly.
The offer (ask, don't auto-skip) is preserved from the original.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two minimal edits to the to-issues skill:
- The "What to build" template now points explicitly at the `/prototype`
skill's code as the source of an inlined decision snippet, rather than
gesturing at "a prototype".
- Publishing now prefers the tracker's native sub-issues (parent → slice)
and native blocking edges (Blocked by) where supported — mechanics
already documented in the issue-tracker doc — keeping the `## Parent`
and `## Blocked by` body sections as the fallback.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Out of scope section: drop embedded 'however sharply you can see it'
duplicate; the 'Scope, not sharpness, lands it here' punchline carries
the claim once.
- Work-through step 5: delegate close+one-line mechanics to the Out of
scope section via the 'rule it out of scope' leading phrase instead of
restating them.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
QA follow-up: the Fog of war section was teaching both concepts, which
muddies the leading word — fog should point only *toward* the
destination. Now Fog of war teaches only the not-yet-specified bucket
(with the two-way fog-or-ticket sharpness test restored), and a new
Out of scope section owns the scope axis: beyond the destination,
closed not graduating, kept out of Decisions so far.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Following review: the map-body headings a cold reader sees should be
self-evident without having read the skill, so drop the metaphor from
the headings — `## Not yet specified` (in-scope, unripe) and
`## Out of scope` (beyond the destination). Keep **fog of war** as the
leading word: it still titles the explanatory section and drives the
"clears the fog" / "graduate the fog" behavior in the prose.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fog is the undiscovered frontier *toward* the destination — in scope,
just not yet sharp — so it graduates into tickets as the frontier
advances. Work ruled out of *this* effort's scope was being parked in
Fog too, where it read as takeable frontier (an unblocked, unclaimed
ticket is indistinguishable from a live one).
Add a dedicated `## Deferred` section for beyond-the-destination work:
it never graduates (the frontier stops at the destination) and returns
only as a fresh effort if the destination is redrawn. The "Fog or
ticket?" test becomes "Fog, ticket, or deferred?", gated on scope as
well as sharpness, and both charting and working-the-map now defer a
mis-scoped ticket (close it, one line in Deferred) rather than leaving
it on the frontier or logging it in Decisions so far.
Builds on #455 (destination as the leading word / destination fixes
scope).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wayfinding finds the way to a destination rather than building it. The
destination varies per effort and is named first, since it shapes every
ticket. Adds a Destination map-body field, makes it triage step 1, and
unifies the stray "goal" mentions onto "destination".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A session now claims a ticket by assigning it to the dev driving the
map, rather than setting a `wayfinder:claimed` label. The assignee is
the claim; an open, unassigned ticket is unclaimed. Reads more naturally
in the tracker's own UI and frees the label vocabulary to
`wayfinder:<type>` alone.
Updates the GitHub and GitLab tracker-operations docs to the assignee
mechanism (`--add-assignee @me` / `--assignee @me`). The local-markdown
tracker keeps its `Status: claimed` line — a file store has no assignee.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Concision pass on the blocking rule (fold the "wherever the tracker has
one" clause into the fallback sentence; drop restatements). Bring the
GitHub and GitLab issue-tracker templates up to the same standard: the
GitHub template now carries the native issue-dependencies recipe and
frontier query; the GitLab template names the native /blocked_by link
(Premium/Ultimate) with the body-convention fallback.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The blocking rule now leads with the tracker's native dependency
relationship and encodes the rationale: native rendering makes the
frontier visible in the tracker's own UI, so the human sees what's
takeable without opening the map. Notes the body-convention fallback
for trackers that lack native blocking (GitHub has it; GitLab only on
paid tiers).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The tdd skill pointed at a `review` skill that no longer exists; the
review skill is now named `code-review`. Update the reference.
Fixes#432
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a hard stop so the agent won't enact the plan until the user
confirms shared understanding is reached. Recruit the pretrained
"grill" leading word in the description, and re-sync the docs page
with the new gate behaviour.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The description does the skill's invocation work, so lead with the trigger
that actually reaches for Wayfinder — a huge chunk of work, more than one
agent session can hold — instead of the softer "chart a route through a
foggy problem". Skill body and fog-of-war mechanic unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Every session ended with a Handoff that queried the frontier and emitted
per-ticket copy-paste commands — real token cost each session. Cut it
entirely and let the natural flow carry continuation: the next
/wayfinder session already loads the map and picks the next frontier
ticket, so nothing is lost, just deferred to re-invocation.
Reconciles the references left behind: the one-ticket-per-session rule
and "charting is one session's work" constraint survive as plain lines;
the Refer-by-name paragraph drops its Handoff mentions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
"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>
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>
User-invoked skill mirroring handoff, but hands the conversation summary
to a fresh background agent via `claude --bg` instead of saving a
markdown document.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The word "branch" in the Invocation section primes git-aware agents
(Sonnet, GPT-5.5) to create git branches when running the skill,
littering established environments with per-session branches that then
have to be merged. Nothing here refers to git — the two "branches" are
the two invocation modes (chart the map / work through it). Rename to
"modes" to remove the false cue.
Fixes#418
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
State the no-duplication contract up front with a leading word: the map
indexes decisions and points at the tickets that hold them; a decision
lives in exactly one place — its ticket — so the map only gists and links.
Also close a fog-vs-ticket duplication: graduating fog into a ticket now
clears the graduated patch from the Fog.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the "one-liner" constraint — fog entries can be as loose or full as
the view allows. Point the map template's Fog comment at the Fog-of-war
section instead of restating it, and remove the duplicated "not a ticket"
now that the keep-out clause covers it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Fog-of-war section explained the loop but not the content. Add
explicit inclusion/exclusion guidance: dim decisions/investigations
coming but not yet specifiable, as rough one-liners — not what's already
decided (Decisions so far) or actionable now (a ticket).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Show the map body (Notes / Decisions so far / Fog) and the ticket body
(Question) as literal markdown templates instead of describing them in
prose, so a charting session reproduces the same shape every run. The
template carries the structure; surrounding prose trimmed to avoid
restating the zone list.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Single-source the frontier and fog definitions. The Tickets section owns
"frontier"; Fog-of-war owns the loop and terminal condition. Remove the
frontier re-definition and fog-nature restatement from Fog-of-war, the
duplicated frontier criteria from the work sequence, the repeated "way to
the goal is clear" from the intro, the "low resolution" restatement, and
the clear-context prose that its own example already shows.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the "shared artifact, not a private file" sentence and the "one URL
the whole team reads" restatement (no-ops the agent obeys by default).
Fold Chart step 4 into step 3 — "don't chart what you can't see" already
lives in the Fog of war section (single source of truth).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move the map off a local Markdown file and onto the repo's configured
issue tracker. The map is a single wayfinder:map issue whose tickets are
its child issues — one shared URL the team can watch and comment on.
Blocking, claiming (wayfinder:claimed), and the frontier query use native
tracker semantics; a session loads the map at low resolution (Notes +
per-closed-ticket context pointers + Fog prose) and zooms into tickets on
demand. Per-tracker mechanics live behind the docs/agents/issue-tracker.md
pointer, so setup-matt-pocock-skills seeds a "Wayfinding operations"
section for GitHub, GitLab, and local-markdown; absent that doc, Wayfinder
defaults to local-markdown.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove the "You are the Wayfinder" second-person persona from the intro,
description, and README so the agent doesn't adopt a persona. Keep the
leading-word frame (chart / fog / frontier / map); wayfinder stays only as
the skill/invocation name.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The persona is the Wayfinder; the invocation should match. Rename the
folder and skill name to wayfinder and update the invocation examples,
README link, and changeset. "wayfinding" stays only as the activity noun.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
