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>
