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>
Reframe the planning skill around the Wayfinder persona — chart a route
through a foggy problem, resolving tickets one at a time until the way to
the goal is clear. "Decision map" was jargony and inaccurate (only 1 of 4
ticket types is a decision).
Rename the folder and skill name, rewrite the description and framing, and
prune: unify node->ticket, bind "frontier" to the unblocked set, drop the
duplicated "one question at a time" (owned by /grilling), trim intro no-ops.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A small, model-invoked skill that spins up a background agent to
investigate a question against high-trust primary sources, then leaves a
single cited Markdown file wherever the repo keeps such notes.
Wires it into the plugin set, both READMEs (Model-invoked), a docs page,
and the ask-matt router, per the repo's promoted-skill conventions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ask Matt was missing five skills that now exist and are user-reachable:
tdd (the red-green engine implement drives), diagnosing-bugs (there was
no route for "something's broken"), domain-modeling and codebase-design
(the two vocabulary references), and grilling (the shared primitive).
- SKILL.md: add a "Something's broken" on-ramp for diagnosing-bugs, a
"Vocabulary underneath" section for domain-modeling/codebase-design,
weave tdd into the main flow, flesh out prototype, broaden the
description from "user-invoked skills" to "the skills".
- docs/engineering/ask-matt.md: re-sync the framing to match.
- CLAUDE.md: add a maintenance rule so any future skill change triggers
an Ask Matt re-check, beside the existing docs-page re-sync rule.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The build chain now ends at code-review. Update every flow doc that draws
the chain so it reads end-to-end:
grill-with-docs → to-prd → to-issues → implement → code-review
- grill-with-docs / to-prd / to-issues: extend the diagram; point the
downstream neighbour at implement (which drives tdd internally).
- tdd: reframe from "final step" to the engine inside implement's step.
- implement: extend the diagram to include the review pass.
- ask-matt: narrate the flow ending in review (docs) and note that
/implement closes out with /code-review (SKILL.md).
- writing-docs guide: refresh the example chain.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rename the in-progress `review` skill to `code-review` and move it from
`skills/in-progress/` into the promoted `skills/engineering/` bucket.
- Add it to `.claude-plugin/plugin.json` and the Model-invoked sections of
the top-level and Engineering READMEs; drop it from the in-progress README.
- Add a docs page at `docs/engineering/code-review.md`.
- Point `/implement` and its docs at `/code-review`.
- Update the smell-baseline changeset reference; add a changeset for the move.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The canonical build chain is grill-with-docs → to-prd → to-issues →
implement, with tdd as the red-green loop implement drives internally
rather than a chain step of its own.
- Update the chain diagram on grill-with-docs, to-prd, to-issues, and tdd.
- Reframe tdd's "Where it fits": it's the engine inside the implement
step, still independently reachable, no longer the terminal.
- Point to-prd and to-issues at implement as the thing that builds the
tickets, giving implement the inbound links it previously lacked.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
misc/ skills are no longer installable via the plugin or listed in the
top-level README — they join personal/ as kept-but-unshipped. Only
engineering/ and productivity/ are promoted now.
- Drop the Misc section from the top-level README.
- Reclassify misc/ as non-promoted in CLAUDE.md (README/plugin rule,
bucket-README grouping rule, docs-page rule) and the writing-docs guide.
- Note the non-promoted status in the misc bucket README.
plugin.json already omitted misc, so no manifest change was needed.
No SKILL.md context pointer referenced a misc skill, so nothing else
had to move.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
misc/ skills are niche — they stay promoted (README + plugin manifest,
so they're installable) but no longer get a public aihero.dev docs
page. Remove the four misc pages and decouple the docs rule from the
promotion rule in CLAUDE.md and the writing-docs guide.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The repeated "The load-bearing constraint:" opener on every page read
as an agent tell. Strip the label across all skill pages and let the
constraint stand as a plain declarative sentence; update the
writing-docs template so it isn't regenerated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
codebase-design, domain-modeling and grilling are pulled out as
standalone, model-invoked skills precisely so other skills can point
at them and so you can reach them as a reference independently of the
steps any wrapper mandates. Add a "Pulled out on purpose" section to
each that names who leans on it and why it stands alone, and slim the
overlapping "Where it fits" prose to avoid duplication.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds a docs page for every promoted skill that lacked one, following
.agents/writing-docs.md and using docs/engineering/to-prd.md as the
worked exemplar. Covers all of engineering/ (bar to-prd, already done),
productivity/, and misc/.
Each page states its load-bearing constraint, its invocation mode and
trigger boundary, surfaces the skill's leading word, and routes back to
ask-matt so the set forms a connected router with no dead ends.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Replace the inline "watch for the leading words" line with an
optional `## It's working if` section — a short list of observable
signals the skill is doing its job. Keeps observability from being
hammered onto leading words specifically.
- Build out to-prd's "What the PRD includes" with proper casing and a
one-line explainer per section.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reframe docs pages around cognitive-load relief: most skills are
user-invoked, so the human is the index that must remember when to
reach for each one. Each page's job is to make one skill memorable
and situate it in the system.
Template changes (.agents/writing-docs.md):
- Quickstart block: install + `npx skills update`, install-first
- New `## When to reach for it` (invocation mode + trigger boundary)
- New optional `## Prerequisites` (workspace/state, prior setup, tooling)
- Free-form middle with one firm rule: surface the leading word
(also an observability signal in the agent's output)
- `## Where it fits`: role-based, absorbs "Pairs well with", links ask-matt
- No H1; every cross-link absolute
Nest docs under bucket folders (docs/<bucket>/<name>.md); the
published URL stays skills-<name> regardless. Re-sync to-prd as the
worked exemplar.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Some blockers are neither a decision, a prototype, nor research — just
literal manual work (moving data, signing up for a service, provisioning
access) that must happen before discussion can move forward.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Relocate this repo's ADRs and invocation.md from docs/ to .agents/,
and update the CLAUDE.md reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Revert Sketch back to Prototype to mesh with the /prototype skill and
existing vocabulary, keeping the generalized function-first definition.
- Move the `## Notes` block from the top of the map to the end.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Decouple the skill from engineering so it plans any domain (e.g. course
content) without specializing toward it. Domain specifics live in the map,
not the skill body.
- Add an optional `## Notes` block to the map: declares the domain + skills
to consult, plus freeform standing preferences. Loaded into every session,
honored by every session, accrues as it emerges.
- Rename the Prototype ticket type to Sketch and define it by function —
raise the fidelity of the discussion with a cheap concrete artifact to
react to (/prototype is one medium among outline/rough-take/stub).
- Note that validation is the thread through all three types, not a type.
- Resolve step now consults skills named in Notes.
The session machinery (one ticket per session, claiming, parallelism,
handoff) is unchanged — it follows from the AI agent's smart/dumb zones, not
the domain.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a header note clarifying that link-skills.sh is a dev-only script for
maintainers, not a supported installer, and that modifications or requests
for modification will not be approved.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Each smell now reads what-it-is → how-to-fix, telegraphic style — the fix
is the actionable half a reviewer needs, kept to a clause.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds Refactoring ch.3 "Bad Smells in Code" into the in-progress `review`
skill. The skill stays two-axis: smells layer into the Standards axis as a
fixed, always-on baseline alongside a repo's documented standards, rather
than a third axis.
Because the baseline is needed on every run it lives inline in SKILL.md.
Each smell is one line — its name carries the definition (the names are
strong leading words) plus a diff-specific cue. Curated to ~12 high-signal
smells; vague ones (Comments, Loops) and tooling-caught ones (Long
Parameter List) are deliberately dropped.
Two rules bind the baseline: a documented repo standard always overrides
it, and every smell is reported as a judgement call, never a hard
violation. The Standards sub-agent prompt now carries the baseline and
these rules.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Refactoring belongs to the review stage, not the implementation loop.
Remove the refactor rule and the now-orphaned refactoring.md (its home is
the review skill), and point the loop's rule at the review skill so it
isn't re-added.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The red → green → refactor loop is anchored by leading words the model
already holds, so the step-by-step Workflow mostly restated the loop and
duplicated the horizontal-slicing anti-pattern. Drop the Workflow and
per-cycle checklist; fold their durable idea (vertical slices / tracer
bullets) into Anti-patterns and a short Rules-of-the-loop list.
Introduce **seam** as the leading word for where tests go, collapsing the
old Philosophy "public interfaces" prose and the Planning "confirm
interface / behaviors" handshake into one rule: test only at pre-agreed
seams, confirmed with the user before any test is written.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tests whose assertion is recomputed the way the code computes it pass by
construction and give zero confidence. Add it as a peer of the existing
implementation-coupling anti-pattern: a Philosophy principle, a per-cycle
checklist gate, and a BAD/GOOD example pair in tests.md. Includes a patch
changeset.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace numeric ticket ids (#1, #2…) with short, token-efficient
dash-case slugs (e.g. relational-db) that read as mini-titles. Update
the Structure example, the next-ticket selection rule (lowest-numbered →
first in document order), the optional-arg wording, and the Handoff
copy-paste examples accordingly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
