Commit Graph
100 Commits
Author SHA1 Message Date
Matt PocockandClaude Opus 4.8 c01d2b6346 refactor(plugin): self-maintaining directory form for plugin skills
Replace the hand-listed 22 skill directories in
.claude-plugin/plugin.json with the two promoted buckets
(./skills/engineering, ./skills/productivity). Claude Code
discovers skills one level down, so newly promoted skills are
picked up automatically and the manifest can't drift out of sync
with the tree. Resolves the same enumeration gap that once left
resolving-merge-conflicts off the list.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-14 10:13:18 +01:00
Matt PocockandGitHub 66898f60e8 Merge pull request #536 from mattpocock/task/claude-codex-plugin
feat: ship the skill set as a native Claude Code plugin (v1.2)
2026-07-13 14:36:01 +01:00
Matt PocockandGitHub 0ac3f3fbf1 Merge pull request #551 from mattpocock/codex-skill-metadata
feat: add Codex agents/openai.yaml metadata to every skill
2026-07-13 13:00:38 +01:00
697d4ce974 feat: add Codex agents/openai.yaml metadata to every skill
Adds an `agents/openai.yaml` beside each `SKILL.md` so the skills work in
Codex as well as Claude Code, without generated copies:

- `interface.display_name` + `interface.short_description` for the Codex
  skill picker, hand-written for all 39 skills.
- `policy.allow_implicit_invocation: false` on the 22 user-invoked skills —
  the Codex analog of `disable-model-invocation: true`, so Codex excludes
  them from implicit invocation while explicit `$skill` still works.
- Document the dual-harness invocation model in `.agents/invocation.md`,
  `CLAUDE.md`, and the promoted-bucket READMEs.
- Add `AGENTS.md` as a symlink to `CLAUDE.md` so Codex reads the same
  instructions; note Codex as a `link-skills.sh` install target.

Slimmed-down rework of the approach prototyped in #522: keeps the essential
cross-harness metadata, drops the Ruby validator, the runtime-detector test,
per-skill `default_prompt`s, and the unrelated promotion changes.

Co-authored-by: gabimoncha <gabimoncha@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 12:57:18 +01:00
Matt PocockandGitHub 8f4952b6a3 Merge pull request #539 from mattpocock/fix/finish-promoted-wiring
fix: finish promoted-bucket wiring for resolving-merge-conflicts and implement
2026-07-13 12:42:15 +01:00
Matt PocockandClaude Opus 4.8 d3275456a4 fix: finish promoted-bucket wiring for resolving-merge-conflicts and implement
Close a standing CLAUDE.md-invariant gap where two promoted skills were
not fully wired into the plugin manifest and READMEs.

- resolving-merge-conflicts (model-invoked): add to .claude-plugin/plugin.json,
  top-level README.md, and skills/engineering/README.md.
- implement (user-invoked): add the missing line to skills/engineering/README.md
  (already present in plugin.json and the top README).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 12:00:09 +01:00
Matt PocockandGitHub 04fee67571 Merge pull request #533 from mattpocock/yagni-scope-improve-architecture
improve-codebase-architecture: scope the scan to where change is landing (YAGNI)
2026-07-13 11:27:15 +01:00
Matt PocockandGitHub 33dfc9b28f Merge pull request #538 from mattpocock/wayfinder/research-subagents
wayfinder: burn research tickets down with subagents
2026-07-13 11:18:20 +01:00
Matt PocockandGitHub 8eb8f58f0f Merge pull request #532 from mattpocock/grill-me-general-use
grilling: reword the primitive for general use
2026-07-13 11:14:03 +01:00
Matt PocockandClaude Opus 4.8 3bb587fa5c Rename "design tree" → "decision tree" across skills and docs
Align the remaining callers and docs pages with grilling's body, which now
says "decision tree".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 11:13:55 +01:00
Matt PocockandClaude Opus 4.8 170ad48655 grilling: reword the primitive for general use
Drop the software-plan scoping from grilling's description and body so the
interview reads as a stress-test of any plan, decision, or idea:
"this plan" → "this", "enact the plan" → "act on it", "codebase" →
"environment". The technique is unchanged, and grill-me is left as-is.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 11:11:58 +01:00
Matt PocockandClaude Opus 4.8 2602257241 feat(wayfinder): burn research tickets down with subagents
Research stays a real ticket type — it's a shared blocker downstream
decisions hang on, which the frontier's blocking edges exist to render.
What changes is resolution: because research is AFK, charting doesn't
stop and read. After creating the tickets, the charting session fires a
/research subagent for each research ticket to burn it down in parallel,
capturing findings on a throwaway research/<name> branch with a context
pointer.

Charting's "fire the research subagents" step owns how research is
handled; the Ticket Types bullet just names the resolver, and the
one-ticket-per-session rule carries the research exception.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 11:10:46 +01:00
Matt PocockandClaude Opus 4.8 45afd8074a improve-codebase-architecture: scope the scan to where change is landing (YAGNI)
Before scanning, decide where to look. If the user named a direction, take
it; otherwise read the last ~20 commit messages to bias exploration toward
actively-developed paths. A deepening opportunity in code nobody touches is a
refactor you'll never cash in — leverage only pays off where you keep editing.

Syncs the docs page and adds a changeset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 11:01:18 +01:00
Matt PocockandGitHub 6704a52ac4 Merge pull request #534 from mattpocock/wayfinder-decision-tickets
Name the wayfinder unit a "decision ticket"
2026-07-13 10:51:13 +01:00
Matt PocockandClaude Opus 4.8 7d694b7ae9 Name the wayfinder unit a "decision ticket"
People kept reading a wayfinder ticket as an ordinary implementation
ticket — a slice of a build to execute — when wayfinder uses them as
decision tickets: questions whose resolution is a decision.

Introduce "decision ticket" as a light leading word: the skill
description and its opening line name it (and say what makes it one),
and the ask-matt / engineering README blurbs and the docs page match,
while "ticket" stays the everyday word once the term is established.
Record "Decision ticket" in CONTEXT.md so the "avoid: ticket" domain
rule no longer contradicts wayfinder's deliberate use of the word.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 10:50:29 +01:00
Matt PocockandGitHub f15b4dca01 Merge pull request #535 from mattpocock/ask-matt-wayfinder-guidance
ask-matt: give /wayfinder real routing help
2026-07-13 10:26:40 +01:00
Matt PocockandClaude Opus 4.8 e74fee89fe ask-matt: give wayfinder real routing help
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>
2026-07-13 10:25:30 +01:00
Matt PocockandClaude Opus 4.8 42a5b70fca feat: ship the skill set as a native Claude Code plugin
Add a Claude Code plugin marketplace so the promoted skills can be
installed as a managed, read-only bundle (subscribe rather than fork),
alongside the existing skills.sh installer.

- Enrich .claude-plugin/plugin.json with marketplace metadata (version,
  description, author, license, keywords); keep the curated promoted-only
  skills array.
- Add .claude-plugin/marketplace.json making the repo its own
  single-plugin marketplace (mattpocock-skills@mattpocock).
- README: document /plugin install alongside skills.sh, and the
  subscribe-vs-fork tradeoff.
- CLAUDE.md: extend the promoted-set invariant to cover marketplace.json
  and plugin.json/package.json version sync.
- ADR 0002: record why Claude ships now and a native Codex plugin is
  deferred (Codex skills field is single-path + drops symlinks, which
  can't express a curated subset of a bucketed repo without a restructure).

Verified: 'claude plugin validate . --strict' passes, and marketplace
add -> install resolves all 21 promoted skills at v1.2.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 10:14:22 +01:00
Matt PocockandGitHub 391a2701dd Merge pull request #505 from mattpocock/add-setup-deep-modules-skill
Add setup-ts-deep-modules skill (in-progress)
2026-07-10 14:14:59 +01:00
Matt PocockandGitHub 2ee14df19c Merge pull request #488 from mattpocock/prototype-primary-secondary-source
prototype: keep the prototype as a primary source
2026-07-10 11:45:42 +01:00
Matt PocockandClaude Opus 4.8 fa460cbf09 prototype: drop the vestigial "let it go"
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>
2026-07-10 11:35:29 +01:00
Matt PocockandClaude Opus 4.8 3687fb4f38 Name lib/ + tests/ as the canonical package subfolders
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>
2026-07-10 10:16:03 +01:00
Matt PocockandClaude Opus 4.8 3ea30afc68 Rename to setup-ts-deep-modules; entry-points model over single barrel
- 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>
2026-07-10 10:10:02 +01:00
Matt PocockandClaude Opus 4.8 f947f93b92 Put the convention README in the packages folder + point CLAUDE.md at it
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>
2026-07-10 09:55:08 +01:00
Matt PocockandClaude Opus 4.8 d80ff7a840 Reference codebase-design as /codebase-design, not a path
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>
2026-07-10 09:53:56 +01:00
Matt PocockandClaude Opus 4.8 0375c88bfb prototype: collapse the when-done section into rule 6
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>
2026-07-10 09:49:44 +01:00
Matt PocockandClaude Opus 4.8 30a9c7447f Add setup-deep-modules skill (in-progress)
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>
2026-07-10 09:49:13 +01:00
Matt PocockandGitHub 89d370d181 Merge pull request #504 from mattpocock/fix/to-tickets-stray-content
fix(to-tickets): remove stray </content> tag
2026-07-10 09:46:06 +01:00
Matt PocockandClaude Opus 4.8 19c50d50fd fix(to-tickets): remove stray </content> tag from skill and docs
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>
2026-07-10 09:45:20 +01:00
Matt PocockandGitHub e4722b8e65 Merge pull request #502 from mattpocock/setup-skill-friendlier
Friendlier setup flow + one-file-per-ticket local tracker
2026-07-10 09:40:15 +01:00
Matt PocockandClaude Opus 4.8 371b9c9c94 prototype: capture the prototype, don't dispose of it
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>
2026-07-10 09:39:52 +01:00
Matt PocockandClaude Opus 4.8 44eed54518 refactor: friendlier setup flow + one-file-per-ticket local tracker
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>
2026-07-10 09:37:25 +01:00
Matt PocockandClaude Opus 4.8 cdec9f6eb2 prototype: simplify to single primary-source idea; dedup branch files
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>
2026-07-09 14:57:48 +01:00
Matt PocockandClaude Opus 4.8 d6274600ab prototype: reframe disposal around primary vs secondary source
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>
2026-07-09 14:53:43 +01:00
Matt PocockandGitHub d574778f94 Merge pull request #353 from mattpocock/changeset-release/main
chore: version skills
2026-07-08 14:20:40 +01:00
Matt PocockandGitHub cc1e24891d Merge pull request #464 from mattpocock/release/v1.1
v1.1: planning-skills unification (breaking) + wayfinder graduation
2026-07-08 14:19:46 +01:00
Matt PocockandClaude Opus 4.8 d6e21b661d docs: list implement in the README's engineering user-invoked skills
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>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 0557d57579 docs: settle wayfinder as a situational on-ramp, not the main entry flow
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>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 639df6e738 Graduate wayfinder to engineering; unify changesets for v1.1
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>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 d29732e49f refactor(to-tickets): cut the two-readings explainer from SKILL.md
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>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 09a72ba465 refactor(to-tickets): prune no-ops from the two-readings intro
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 386d4ff719 refactor: unify planning skills into /to-spec + /to-tickets
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>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 c5a4a8c2e9 refactor(to-plan,to-issues): prune no-ops in vertical-slice framing
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>
2026-07-08 14:13:21 +01:00
Matt PocockandClaude Opus 4.8 93f73198e3 feat(to-plan): add sequential plan skill
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>
2026-07-08 14:11:05 +01:00
Matt PocockandGitHub 896f14d9c2 Merge pull request #472 from mattpocock/fix/wayfinder-tracker-indirection
fix(wayfinder): resolve issue-tracker doc via the CLAUDE.md pointer, not a hardcoded path
2026-07-08 11:18:12 +01:00
Matt PocockandClaude Opus 4.8 d869d45afc fix(wayfinder): resolve issue-tracker doc via the CLAUDE.md pointer, not a hardcoded path
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>
2026-07-08 11:17:29 +01:00
Matt PocockandGitHub 8515a080a7 Merge pull request #469 from mattpocock/to-issues/wide-refactor-expand-contract
to-issues: slice wide refactors by expand–contract
2026-07-07 16:37:10 +01:00
Matt PocockandClaude Opus 4.8 f219e66379 to-issues: wrap issue template in XML tags
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 16:35:57 +01:00
Matt PocockandClaude Opus 4.8 aa591116bf to-issues: split into Process + Reference tiers
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>
2026-07-07 16:35:39 +01:00
Matt PocockandClaude Opus 4.8 a0329ba957 to-issues: slice wide refactors by expand–contract
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>
2026-07-07 16:32:47 +01:00
Matt PocockandGitHub 16a2a5cd00 Merge pull request #461 from mattpocock/fix/wayfinder-self-grilling
wayfinder/grilling: stop the agent grilling itself
2026-07-06 14:01:24 +01:00
Matt PocockandClaude Opus 4.8 ce908a6220 Add changeset for the self-grilling fix
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-06 13:59:13 +01:00
Matt PocockandGitHub d05f2fb5b5 Merge pull request #463 from mattpocock/negative-space-prompting
writing-great-skills: add Negation failure mode
2026-07-06 13:58:22 +01:00
Matt PocockandClaude Opus 4.8 e5932a7a47 wayfinder/grilling: stop the agent grilling itself
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>
2026-07-06 13:57:47 +01:00
Matt PocockandClaude Opus 4.8 af6d6922c3 Drop Negative Space; keep Negation only
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>
2026-07-06 13:57:05 +01:00
Matt PocockandClaude Opus 4.8 30afefecc9 changeset for Negation and Negative Space failure modes
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-06 13:56:16 +01:00
Matt PocockandGitHub acf55d88b7 Merge pull request #462 from mattpocock/wayfinder/plan-not-execute
wayfinder: reassert planning-only purpose
2026-07-06 13:55:01 +01:00
Matt PocockandClaude Opus 4.8 0847bb31bc writing-great-skills: add Negation and Negative Space failure modes
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>
2026-07-06 13:54:46 +01:00
Matt PocockandClaude Opus 4.8 7be28cf5e6 wayfinder: planning by default, overridable via Notes; shrink section
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>
2026-07-06 13:53:59 +01:00
Matt PocockandClaude Opus 4.8 80f29a4f29 wayfinder: reassert planning-only purpose with a leading-word section
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>
2026-07-06 13:49:33 +01:00
Matt PocockandGitHub 5a7f7e5c2a Merge pull request #460 from mattpocock/wayfinder-no-fog-early-exit
wayfinder: restore no-fog early exit
2026-07-06 13:42:16 +01:00
Matt PocockandClaude Opus 4.8 9b43c3359b wayfinder: simpler no-fog wording — 'you don't need a map'
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-06 13:40:26 +01:00
Matt PocockandClaude Opus 4.8 ad99c73a2d wayfinder: reframe no-fog exit as too-small-for-a-map
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>
2026-07-06 13:38:59 +01:00
Matt PocockandClaude Opus 4.8 55511cea24 wayfinder: restore no-fog early exit
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>
2026-07-06 13:36:44 +01:00
Matt PocockandGitHub d11147daaf Merge pull request #459 from mattpocock/to-issues-sub-issues-and-prototype
to-issues: prefer native sub-issues; reference /prototype code explicitly
2026-07-06 13:35:18 +01:00
Matt PocockandClaude Opus 4.8 0172e61e57 to-issues: prefer native sub-issues; reference /prototype code explicitly
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>
2026-07-06 13:33:44 +01:00
Matt PocockandGitHub 66f92b61f5 Merge pull request #456 from mattpocock/wayfinder-deferred-section
wayfinder: split the map catch-all into Not yet specified / Out of scope
2026-07-05 18:37:09 +01:00
Matt PocockandClaude Opus 4.8 97dca07b64 Duplication pass: collapse restated out-of-scope mechanics
- 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>
2026-07-05 17:48:56 +01:00
Matt PocockandClaude Opus 4.8 7d34a8dc38 Split fog and out-of-scope into separate explanatory sections
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>
2026-07-05 17:44:13 +01:00
Matt PocockandClaude Opus 4.8 3ea01314c1 Rename the two buckets to plain map headings: Not yet specified / Out of scope
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>
2026-07-05 17:35:50 +01:00
Matt PocockandClaude Opus 4.8 299eb0c017 Give wayfinder a distinct Deferred section for beyond-destination work
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>
2026-07-05 15:08:48 +01:00
Matt PocockandGitHub 4691566bbb Merge pull request #455 from mattpocock/wayfinder-destination-purpose
Reframe wayfinder around "destination" as the leading word
2026-07-05 15:03:18 +01:00
Matt PocockandClaude Opus 4.8 913a105881 Split charting triage into two grilling steps: destination, then frontier
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-05 15:02:39 +01:00
Matt PocockandClaude Opus 4.8 c808f64f92 Make triage step 1 breadth-first: fix scope, then find the frontier
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-05 15:00:34 +01:00
Matt PocockandClaude Opus 4.8 53c6219cd2 Reframe wayfinder around "destination" as the leading word
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>
2026-07-05 14:57:57 +01:00
Matt PocockandGitHub 272f99b225 Merge pull request #436 from mattpocock/wayfinder-assign-to-claim
wayfinder: claim by assigning the ticket, not a label
2026-07-03 11:37:11 +01:00
Matt PocockandClaude Opus 4.8 6f9e9956fd wayfinder: claim by assigning the ticket, not a label
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>
2026-07-03 11:34:42 +01:00
Matt PocockandGitHub efa058a349 Merge pull request #435 from mattpocock/wayfinder-native-blocking-rationale
wayfinder: prefer native blocking, and say why
2026-07-03 10:44:51 +01:00
Matt PocockandClaude Opus 4.8 8c2a4c554a wayfinder: tighten blocking rule, update GH/GL templates
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>
2026-07-03 10:42:56 +01:00
Matt PocockandClaude Opus 4.8 b289481499 wayfinder: prefer native blocking, and say why
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>
2026-07-03 10:39:04 +01:00
Matt PocockandGitHub e9dea692fd Merge pull request #434 from mattpocock/fix/tdd-code-review-reference
docs: fix tdd skill reference to code-review skill
2026-07-03 10:02:26 +01:00
Matt PocockandClaude Opus 4.8 bd453a6742 docs: fix tdd skill reference to code-review skill
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>
2026-07-03 09:53:34 +01:00
Matt PocockandGitHub aed86f6b35 Merge pull request #433 from mattpocock/grilling-gate-and-leading-word
grilling: add confirmation gate and grill leading word
2026-07-03 09:49:36 +01:00
Matt PocockandClaude Opus 4.8 e1c025eaee Add minor changeset for grilling gate and leading word
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-03 09:48:46 +01:00
Matt PocockandClaude Opus 4.8 0e9a072792 grilling: add confirmation gate and grill leading word
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>
2026-07-03 09:47:48 +01:00
Matt PocockandGitHub 1445797da5 Merge pull request #428 from mattpocock/wayfinder-plan-big-work
wayfinder: reframe description around planning big work
2026-07-02 14:29:34 +01:00
Matt PocockandClaude Opus 4.8 8cc3328633 wayfinder: reframe description around planning big work
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>
2026-07-02 14:28:49 +01:00
Matt PocockandGitHub 5f45f2e35a Merge pull request #409 from mattpocock/research-skill
Add the research skill
2026-07-02 14:06:32 +01:00
Matt PocockandGitHub 728826c9d2 Merge pull request #425 from mattpocock/wayfinder-remove-handoff
wayfinder: remove the Handoff ceremony
2026-07-02 13:49:30 +01:00
Matt PocockandClaude Opus 4.8 1f16ea9499 wayfinder: remove the Handoff ceremony
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>
2026-07-02 13:48:13 +01:00
Matt PocockandGitHub a83f22b60f Merge pull request #421 from mattpocock/add-claude-handoff-skill
Add claude-handoff skill (in-progress)
2026-07-02 11:33:48 +01:00
Matt PocockandClaude Opus 4.8 b25e2b3787 claude-handoff: add to in-progress README index
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:32:04 +01:00
Matt PocockandGitHub e0d0d84274 Merge pull request #422 from mattpocock/wayfinder-refer-by-name
wayfinder: refer to maps and tickets by name, not id
2026-07-02 11:31:36 +01:00
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 5a7ee93f01 claude-handoff: say handoff summary, not document
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:26:55 +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 8347a41614 claude-handoff: require descriptive --name
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:25:18 +01:00
Matt PocockandClaude Opus 4.8 8f3401d1a1 claude-handoff: reuse original handoff wording
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:24:51 +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
Matt PocockandClaude Opus 4.8 f8d12710f7 Add claude-handoff skill (in-progress)
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>
2026-07-02 11:22:35 +01:00