Repository navigation
v6.0.0 beta - #224
Draft
mxriverlynn wants to merge 94 commits into
Draft
v6.0.0 beta#224mxriverlynn wants to merge 94 commits into
mxriverlynn wants to merge 94 commits into
Conversation
han-plugin-builder teaches authors to write for Sonnet 5, Opus 5, and
Fable 5 as checked on 2026-07-31. Opus 5.5 has shipped, and it refuses
reasoning-echo instructions, cannot turn thinking off, reads effort
levels differently, and stops long runs early to report.
Evaluate the whole plugin against the Opus 5.5 article (primary), the
"How we use skills" post, the context-engineering post, and Anthropic's
Opus 5.5 prompting page. Twenty-eight candidates went through
adversarial validation; eighteen change entries survive, in five units:
- Per-model facts: add Opus 5.5 to per-model-authoring.md and its four
mirrors, extend the reasoning-echo warning, the thinking clause, the
effort re-test note, and separate vague review limits from a checkable
bar.
- Long runs and delegation: name the stops an autonomous stretch should
and should not make without touching collaborative stops, bound
unbounded steps with a finish line and a task file, check fanned-out
evidence, and wait for background dispatches.
- Instruction style: a limit on "be specific", a removal bullet for
instructions restating model defaults, and a gotchas category.
- Baseline skill patterns: verification skills, skill state kept in
${CLAUDE_PLUGIN_DATA}, helper-script libraries, and a skill-scoped
guardrail hook.
- Builder routing: skill-builder and agent-builder read and review
against the per-model guide.
The operator approved all four behavior-changing decisions. The plan,
its decision log, the current-state findings, and the scope boundary
live in docs/plans/opus-5-5-plugin-builder-guidance/. No plugin file
changes in this commit.
The per-model guide covered Sonnet 5, Opus 5, and Fable 5 as checked on 2026-07-31. Opus 5.5 has shipped with behavior that changes what an author writes. - Name Opus 5.5 and state that it inherits the Opus 5 guidance except where a section says otherwise, per Anthropic's Opus 5.5 page. - Extend the reasoning-echo warning to Opus 5.5 and name the reasoning_extraction refusal category. - Note that Opus 5.5, like Fable 5, cannot turn thinking off. - Tell authors that effort names mean more thinking on Opus 5.5, and to re-test a pinned effort value rather than carry it over. - Keep the warning against vague review limits, and add that a limit naming a checkable bar with per-item evidence is fine. - Add the Opus 5.5 sources and a Contents list. Mirror the model list in the guidance router, the portable router, the rule index, and the specialization guide, and point both frontmatter tables' effort rows at the effort guidance. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 1, S-1 to S-6).
Opus 5.5 works longer on its own and sometimes ends a turn with a progress report instead of the next step. The guidance covered deliberate human gates, but not that. - workflow-patterns.md: name the stops an autonomous stretch should and should not make, and keep the keep-going instruction out of any skill built to hand control back. Bound a step that works through an unknown number of items with a checkable finish line and a checklist file that survives context summarization. - multi-agent-economics.md: when fanning out, check each subagent's cited evidence before accepting its finding, and do not finish while a run_in_background dispatch is still running. - agent graceful-degradation.md: a research or analysis agent marks a claim it could not confirm and says where it looked. - per-model-authoring.md: name Opus 5.5's early-stop behavior and link the pattern. - agent-builder Step 6 item 8 names both degradation rules, and the rule index describes the widened files. The stop-naming section describes collaborative stops rather than linking han-core's collaborative-stop rule, because this guidance is vendored into other repos by `guidance init`, where that link would not resolve. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 2, S-7 to S-10).
Anthropic's skills and context-engineering posts report that Claude 5 generation models are over-constrained by blanket rules, that restating default behavior adds tokens without changing output, and that a gotchas list is the highest-signal content a skill carries. The guidance pushed toward specificity with no limit, removed only toolchain-enforced rules, and had no gotchas category. - writing-effective-instructions.md: spend specificity where a miss breaks something, and leave out rules for details the model gets right unprompted. The rule governs instruction detail, not whether a step is fixed, and links the entity taxonomy's flowchart test. - progressive-disclosure.md: list instructions that restate model defaults as removable, and name gotchas as a reference category. - skill-reference-files.md: define gotchas as failure points found in use, distinct from a checklist or a canonical example. - Rule index describes the widened files. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 3, S-11 to S-13).
…s, and skill hooks
Anthropic's skills post describes four patterns the guidance lacked.
- success-criteria-and-testing.md: how to build a skill whose job is
verifying a running product: pair it with a driver, assert state at
every step, and record the run.
- plugin-json-options.md: keep a plugin-shipped skill's first-run
answers and run history in ${CLAUDE_PLUGIN_DATA}, never in the skill
directory, which ${CLAUDE_PLUGIN_ROOT} replaces on update. Name
userConfig, hand-edited files, and repo-checked-in skills as the
cases that need something else. allowed-tools-AskUserQuestion.md
links to it.
- hardening-fuzzy-vs-deterministic.md: a library of helper functions
the model composes into one-off scripts, which still prompt for
permission. Adds a Contents list now that the file is over 100 lines.
- skill-frontmatter-fields.md: a skill-scoped hook lasts only for the
run, which suits a guardrail such as blocking destructive commands.
- Rule index describes the widened files.
The state section does not say whether saving to ${CLAUDE_PLUGIN_DATA}
prompts for permission, because no source this plan used states it.
Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 4, S-14 to S-17).
…r-model guide Neither builder read per-model-authoring.md or reviewed against it, so the Opus 5.5 guidance reached only people who asked the guidance skill directly. - Both decision tables route "instructions for a named target model" to per-model-authoring.md. - Both Step 6 reviews gain a model-specific-leftovers item: no "think step by step" line, no instruction to reproduce reasoning in the reply, no pinned effort without a stated reason, and no vague limiting phrase in a review step, with one passing and one failing example quoted. - skill-builder's progressive-disclosure item also cuts instructions that restate a default the model already follows, matching the guidance change in progressive-disclosure.md. Also rewraps the specialization guide's per-model cross-reference, which the Opus 5.5 addition pushed past 120 characters. Plan: docs/plans/opus-5-5-plugin-builder-guidance (Unit 5, S-18).
…ection Found by the /han-update-documentation pass over the branch.
…lder docs The skill-builder and agent-builder long-form docs now say the review pass strips model-specific leftovers and that per-model authoring is a governing document in the design-tree map, matching the SKILL.md changes on this branch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
check-cross-references.sh and check-plan-cross-references.sh find an entry's
heading in awk with the interval expression #{2,4}. mawk 1.3.4 20240123, the
default awk on Ubuntu 24.04, matches only two hashes with it, so the
"### F1:" and "### D-1:" headings the templates produce are never read.
On that awk a valid review fails with empty-field for every finding, and a
decision log that cites a plan section the plan does not have passes. Eleven
of the two scripts' Bats tests fail there; CI runs gawk, so it stays green.
Spell the level as ###?#?, which every awk reads the same way, and add a
four-level heading test to each suite.
…ops-engineer and on-call-engineer
…minimal tools, data-engineer reverse boundary)
…lls, and gap-analysis dispatch
…skill doc updates
Adds `han-core:observability-engineer`, an adversarial reviewer for telemetry design, and wires it into every skill that routes observability today. ## Why Research ([docs/research/observability-engineer-research.md](docs/research/observability-engineer-research.md)) found that Han already covers most of observability. `devops-engineer` owns SLOs, burn-rate alerting, dashboards, and the golden signals. `on-call-engineer` owns source-line debuggability, correlation IDs, and PII in log statements. What nobody owns is the design layer between them: how telemetry is named, metric label cardinality and what it costs, whether sampling keeps the error and slow traces, and how the telemetry pipeline is configured. Those problems fall between the two reviewers at both the code and configuration levels. Adversarial validation narrowed the recommendation from a broad observability owner to this telemetry-design slice. The broad version would have rewritten two working agents. ## What changed - **New agent:** `han-core/agents/observability-engineer.md` - `opus`, read-and-report only. - Content: 9 named anti-patterns, 7 protocols, `OBS-###` findings. - Names both the metrics-first and events-first schools and recommends whichever fits the existing stack. - Carries a YAGNI guard for small, low-traffic services. - **Two-way boundaries:** `devops-engineer`, `on-call-engineer`, and `data-engineer` each point back to the new agent. The `on-call-engineer` and `data-engineer` descriptions were trimmed to stay within the 1024-character budget. - **Dispatch wiring:** code-review, architectural-analysis, iterative-plan-review, plan-a-feature, plan-a-change, plan-implementation, and gap-analysis. Each gets a selection signal, a scoped brief, and a report or plan section. - **Docs:** long-form doc `han-core/docs/agents/observability-engineer.md`, the `han-core` README line, the agents index, the sibling agent docs, and the roster docs. ## Not in this PR - No CHANGELOG entry or version bumps; `/han-release` owns those. - Pre-existing issues I left alone: - Sentence fragments below the opening paragraph of `on-call-engineer.md` and `devops-engineer.md`. - architectural-analysis never lists `OCE-###` in its verbatim-ID step. ## Testing - `npm test`: all 121 tests pass. - `npm run lint`: all non-formatting hooks pass, and Prettier is clean on every changed file. - Lint also reformats existing `evals/` files on `main`. I reverted those changes, so they are not in this PR. **Open check:** the research's reopen trigger still applies. Run the agent on a few real telemetry changes. If it finds nothing `devops-engineer` and `on-call-engineer` would not, fold its checks into `devops-engineer`.
…aits on the operator
… fold in review round findings
… from the skill Merges the signal and file-list slice tables into one roster table with output-file and series columns, points Step 7.1 and verification item 2 at it, and replaces each prompt's "Write your output to" with a hand-back sentence the skill files from (S-1, S-2, S-31).
… rule Deletes the size classifier and every size reading, drops a lone retired size word with a one-line note, puts the default severity rule in the Step 3.3 calibration directive for manual and agent findings alike, and stops code review reading default-swarm-size (S-3, S-4, S-20, S-25 size wording).
The red-step revert restored touched files from git whenever the tree was clean at the start of the run. Commits during a run are optional, so a restore reset a shared file to its last commit and discarded earlier green steps that were not yet committed. Undo the step's own edits directly and never use checkout, restore, reset --hard, clean, or stash to undo a step. Co-Authored-By: Claude <noreply@anthropic.com>
## Summary The refactor skill's red-step revert could throw away finished work. **The bug.** On a red suite, the skill ran `git checkout`/`git restore` on the touched files whenever git was available and the tree was clean *at the start of the run*. Commits during a run only happen if you ask for them, and even then can be grouped. Git restores a file to its last commit, so when two steps touch the same file with no commit between them, reverting the second step also discarded the first, already-green step. That contradicted the skill's own stop-rule promise that "everything already applied is green and stands." **The fix.** A red step now undoes only its own edits directly: reverse each edit, delete any file the step created, and move renamed or moved files back. The skill never restores files from git to undo a step, never runs `git reset --hard`, `git clean`, or `git stash` for it, and re-runs the suite to show the revert is back to green. ## Changes - `han-coding/skills/refactor/SKILL.md`: Step 4, item 4 rewritten. - `han-coding/docs/skills/refactor.md`: the "what you get" bullet now says a revert touches only that step's edits. Found during the Mikado Method research in #228. That research's Mikado recommendations are deliberately out of scope here. ## Test plan - [x] `npm run lint` passes - [x] `npm test` passes - [ ] Manual: run `/refactor` on a target where two planned steps edit the same file, with no commits requested, and force the second step red; confirm the first step's change survives the revert. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Han's review loops could only say 'this finding, this fix'. A plan that kept drawing edge-case findings on one mechanism ran to its round cap while being patched, and nothing asked whether a different tool or shape would make the whole class of findings moot. The investigation is in docs/plans/review-loop-approach-reassessment/investigation.md. Add /reassess-approach: it gathers a plan or code unit, its recorded findings, and the reason it is asked, dispatches one han-core:software-architect critic in a fresh context, and returns structurally different alternatives, always including stop and continue, as one options report and one question. iterative-plan-review (team mode) and plan-implementation (medium and large) invoke it at their round cap when the convergence condition still fails; small runs end with a pointer instead. Docs, catalogs, and an eval suite with a regex-parser fixture are included. Plugin versions and the changelog are untouched. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…r stalled units Coordinates architectural-analysis, plan-a-change (or its own plan when han-planning is absent), and refactor or tdd per unit, after one start gate. A unit that stalls becomes the goal of a Mikado graph: attempt, record prerequisites, undo with undo-attempt.sh, and work leaves first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d workflow map Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ap (#231) ## Summary Han's review loops could only say "this finding, this fix". A plan that kept drawing edge-case findings on one mechanism ran to its round cap while being patched, and nothing ever asked whether a different tool or shape would make the whole class of findings moot. The investigation behind this change is in `docs/plans/review-loop-approach-reassessment/investigation.md`. This PR adds `/reassess-approach` to `han-planning`. It gathers a plan or code unit, the findings it has absorbed, and the reason it is being asked, then dispatches one `han-core:software-architect` critic in a fresh context with only that material. The critic returns structurally different alternatives, always including "stop doing this" and "continue as is", each citing the recorded findings it would make moot, what it adds and removes in owned code paths or plan items, and what to run next. The skill writes one options report and changes nothing; the decision comes back to the person as one question. `/iterative-plan-review` (team mode) and `/plan-implementation` (medium and large) invoke it when they reach their round cap without converging, record the result as an `approach` finding or ledger tag, and present the options through their existing question channel. Small runs, capped at one round, do not hand off: one pass cannot tell a plan stuck on its approach from a plan that needed edits, so they end with a one-line pointer to the skill instead. The skill is also invocable by hand on any plan or code path. ## Key file changes - `han-planning/skills/reassess-approach/SKILL.md` and `references/approach-reassessment-template.md`: the new skill and its report template. - `han-planning/skills/iterative-plan-review/SKILL.md`: `approach` as a major category, the team-mode hand-off at the cap, the lightweight pointer, and the closing-question wording. `references/review-findings-template.md` gains the category and an `Alternatives:` field. - `han-planning/skills/plan-implementation/SKILL.md` and `references/round-aggregation.md`: the facilitation-plateau note becomes the hand-off at medium and large, with an `approach` ledger tag. - `han-planning/skills/plan-a-change/SKILL.md`: reverse boundary clause so disambiguation runs both ways. - `han-planning/docs/skills/reassess-approach.md`, plugin README, skills index, `docs/workflows.md`, `docs/concepts.md`, `docs/readability.md`, `docs/yagni.md`, `docs/evidence.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and the `software-architect` agent doc: documentation and catalog coverage. - `evals/reassess-approach/`: five trigger tests and one functional test over a scaffold with a hand-written regex parser, a plan that commits to it, and three rounds of clustered edge-case findings. Plugin versions and `CHANGELOG.md` are untouched. Manifest descriptions list the new skill. ## Test Plan - [x] `npm run lint` passes on every tracked file touched; a direct `prettier --check` passes on the new files. - [x] `npm test`: the suite could not complete in the authoring sandbox (its temp directory is unwritable). The branch changes no shell script or `.bats` file, and the suite passed 121/121 on this branch before the final Markdown-only edits. Please run it once locally. - [x] Run the `evals/reassess-approach` suite. The functional case is the first measurement of whether the critic's alternatives are structurally different rather than nearby variants. - [ ] Run `/iterative-plan-review large` over a plan whose findings file is at the cap and confirm the closing question carries the options. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
…and plan-a-change to it Adds restructure to pairing's flagged skills and to the collaborative-stop rule (canonical and both vendored copies, still byte-identical), and gives refactor and plan-a-change routing lines toward restructure. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Moves the missing-test-command case out of the hard-failure list and into the start gate, says what happens when a Mikado leaf stalls, and renames the test fixture's folder so no conventional source path appears. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts: # docs/concepts.md # han-planning/skills/plan-a-change/SKILL.md
…232) ## Summary **This PR adds a `restructure` skill that reorganizes a codebase toward a target layout one committed unit at a time, so that a large restructure can run unattended without changing behavior.** ## Behavior changes The new `han-coding:restructure` skill coordinates the work and leaves the code changes to existing skills. You state a goal, such as "group each package by feature." The skill discovers the project's layout, commands, test roots, and documented structure rules at runtime, so it works on any codebase. It shows all of that at one start gate and then asks nothing further. After you confirm, it runs `architectural-analysis`, plans ordered units, and hands each unit to `refactor` or `tdd`. Each green unit is committed on the current branch, and every decision goes into a change log with its justification. The skill never pushes, never switches branches, and never edits a test to make a unit pass. When a unit stalls because its code is too tangled to move in one step, the skill switches to the Mikado Method. It tries the change, records what breaks as prerequisites in a graph committed to the repo, undoes the attempt, and does the prerequisites first. A bundled `undo-attempt.sh` script restores the tree to the last commit. It refuses to run if HEAD has moved, and it removes only untracked files that git does not ignore, which is why the skill requires a clean tree at the start. Discovery stops after five rounds per stalled unit by default; the unit is then logged as not done and its dependents are skipped. Three existing skills route work differently. `pairing` can now drive `restructure`, stopping after each unit so you can review the commit. The descriptions of `refactor` and `plan-a-change` now point to `restructure` for whole-area work. `han-coding` gains no dependency on `han-planning`: when `plan-a-change` is not installed, `restructure` writes the unit plan itself and records that in the change log. The research report behind the design is included at `docs/research/mikado-method-skill.md`.
Move the bug-specific approach, dispatch, analysis, validation brief, audience, and stop into references/types/bug.md, and the report layout into references/templates/bug.md with the shared evidence and validation sections in references/evidence-and-validation.md. SKILL.md keeps the shared flow, gains the Investigation Types table and type-file contract, parses a leading type token and trailing report path, announces the resolved type before dispatch, and pins where the report is written. A Bats test holds the table, type files, templates, and argument-hint in agreement.
Add the how-it-works type file and template, the detection and fit-check examples, and the how-it-works token in the argument-hint and description. Redraw the boundaries in the same commit so no two skills claim one question: research covers the open web and prior art, investigate covers questions this codebase alone can answer, and code-overview and code-walkthrough send a single how-it-works question to investigate. Add a ruby-shop eval scaffold, a how-it-works eval, and a prior-art eval that must not trigger investigate.
Mark the Bats file executable and tell shellcheck the backticks in its patterns are literal Markdown.
Add the available-options type file and template, its table row between bug and how-it-works so it wins the tie-break over how-it-works, its token in the argument-hint and description, detection examples, and an available-options eval on the ruby-shop scaffold.
Rewrite the investigate long-form doc around the bug, how-it-works, and available-options types. Update investigate-to-confluence to accept any type, pass a named type first and its /tmp report path last, and stop before implementing anything. Refresh the han-coding and han-atlassian README scent lines, the skills index, the han-coding plugin description, the workflows map, and the research-a-decision how-to.
…-options (#235) ## Summary **`/investigate` now runs as one of three investigation types: `bug`, `how-it-works`, or `available-options`.** Name the type first, or leave it out and the skill picks one from the question. A named type that clearly does not fit the question gets one question asking which to use. A `bug` run writes the same report sections it wrote before. - Each type is a data file under `han-coding/skills/investigate/references/types/` (detection signals, dispatch roster, analysis steps, validator brief, audience, stop) with its own report template under `references/templates/`. The evidence and validation sections every report shares live once, in `references/evidence-and-validation.md`. - `SKILL.md` keeps the shared flow and owns the only list of type tokens. Every run opens with a block naming the type, why it was chosen, the question as read, and the report path. - `investigation-types.bats` holds the table, type files, templates, `argument-hint`, and description in agreement. - The boundaries are redrawn: `research` covers the open web and prior art, `investigate` covers questions the codebase alone can answer, and `code-overview` and `code-walkthrough` send a single how-it-works question to `investigate`. `investigate-to-confluence` accepts every type. - The plan, findings, and decision log are in `docs/plans/investigate-types/`. **Not verified yet:** the new evals in `evals/investigate/` have not been run, because there is no `tests.json` runner in the repo. No type has had an end-to-end trial run. ## Before requesting review **Do not bump the plugin version and do not edit `CHANGELOG.md` in this PR.** Both are handled by the `/han-release` skill when a release is cut. - [ ] Read [CONTRIBUTING.md](../CONTRIBUTING.md) and confirm the changes follow the rules for the entity being touched. - [ ] Walk the [self-review checklist in CONTRIBUTING.md](../CONTRIBUTING.md#reviewing-your-own-changes). - [ ] Confirm the writing follows [`han-communication/references/writing-voice.md`](../han-communication/references/writing-voice.md). - [ ] Run `/investigate` locally once per type and confirm each works end-to-end. - [ ] Run `/han-update-documentation` from this branch. - [ ] Run `/update-pr-description` to write the final description.
… from the builder skills
…structure and tdd
… correct overview and walkthrough output details
… check, and reassess back-references
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
v6.0.0 Beta
install:
/marketplace add git@github.com:testdouble/han#v6.0.0-beta/plugin install ha@han- or any other specific Han pluginIncludes the following: