Repository navigation
v6.0.0 beta - #224
Draft
mxriverlynn wants to merge 66 commits into
Draft
v6.0.0 beta#224mxriverlynn wants to merge 66 commits into
mxriverlynn wants to merge 66 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).
Names review types in code-review's description and TL;DR, says what the run writes and where, and lists /code-review among gap-analyzer's callers.
Gives on-call-engineer a type that always runs it, with concurrency-analyst when relevant, and moves both out of observability and architecture so those types stay on telemetry and structure. The default run's roster is unchanged.
Gives data-engineer a type that always runs it, with on-call-engineer when relevant for migrations co-deployed with dependent code, and moves data-engineer and the Database category out of architecture. The default run's roster and checklist union are unchanged.
Gives devops-engineer a type that always runs it, with data-engineer when relevant for expand-and-contract migrations, and moves devops-engineer out of observability and the Packaging category out of maintainability. The default run's roster and checklist union are unchanged.
Gives information-architect and content-auditor a home in code review, with roster rows, dispatch prompts, finding rubrics, and manual-sweep mappings. content-auditor runs when an existing doc was modified and its prior version is in git; the skill writes that version under doc-baseline/ for the agent, which has no git access. docs stays outside the default set.
Gives user-experience-designer a home in code review, with a roster row gated on interface files, a dispatch prompt, a finding rubric, and a manual-sweep mapping. No checklist category covers usability, so the type carries none. ux stays outside the default set.
Updates the code-review and post-code-review-to-pr long-form docs, the configuration guide, and the code-review how-to with the new types and the default set, and notes in the information-architect, content-auditor, and user-experience-designer docs that code review now dispatches them.
## Summary **This PR replaces code review's size options with named review types, so that you can run several focused reviews of the same branch in parallel and each report stays on its one concern.** ## Behavior changes Code review now gets its focus from a named review type (such as `security`, `testing`, or `work-ticket`) instead of a size. Every review uses one default rule for how severe a finding is, and each run writes to its own folder. The plan behind this is at `docs/plans/code-review-types/`. This branch carries the plan and all eight units that implement it. 1. **Size words do nothing.** `/code-review large` runs the default review and prints a note that the word was ignored. In `/code-review large file uploads`, all three words are now read as focus text. Before, this ran a Large review focused on "file uploads". 2. **The default size setting no longer affects code review.** A project with `default-swarm-size: large` used to get every review at Large. Now it gets the default severity rule, and the review says nothing about the change. Other skills still read the setting. 3. **Minor suggestions change, and large changes block less often.** A review of one to three files now lists the suggestions the change introduced; before, it hid them. A review of more than ten files no longer lists old suggestions the change did not cause. On a change of more than ten files, a borderline issue is now a suggestion instead of a warning, so a PR review whose only warnings were borderline now posts as a comment rather than requesting changes. Clear-cut problems still block, and a review type can set its own severity rule. 4. **A focused review skips security and does not say so.** `/code-review testing` runs no security check, and its report does not mention that. A bare `/code-review` still runs security. 5. **Agent working files go into a folder per run, and typed reports get a suffix.** For example, `docs/security-analysis.md` becomes `docs/code-review-my-branch/security-analysis.md`, and a testing review's report becomes `docs/code-review-my-branch--testing.md`. A bare review's report keeps its name, unless the old name held characters other than lowercase letters, digits, and hyphens. One folder per branch and type stays on disk. 6. **Every report names its type, and so does the PR it is posted to.** A one-line header says which review type produced it. 7. **Posting to a PR can start a typed review.** If the text after `/post-code-review-to-pr` begins with a type name, as in "testing the retry logic", the skill now runs a `testing` review. 8. **The review states its type before it starts.** The announcement now comes at the end of Step 1, before the automated checks. It shows the type's purpose and your focus text. A bare review lists the available types. 9. **Findings from every specialist reach the report.** Each specialist (a sub-agent the review dispatches) either saves its findings to a file and says where, or hands them back directly. The review uses whichever one it gets. Findings from the three specialists that could not save files, and from your extra agents, now show up in reports where they may have been silently missing before. This PR does not edit CHANGELOG.md, because the han-release skill writes it at release time. These nine items are what the changelog should record. ## What to look at first - **The type-file contract and the `## Review Types` section in `han-coding/skills/code-review/SKILL.md`.** Each shipped type is a data file under `references/types/`. The table in this section is the only list of shipped type tokens. The bare default run takes the union of five types' rosters but applies none of their severity overrides or report sections. Teams can declare their own types under `## Code Review Types` in `.han/config.md`, and they can attach agents to a type under `## Code Review Type Agents`. - **The single roster table and the hand-back or file rule in `references/agent-dispatch.md`.** The signal table and the slice table are now one table with output-file and series columns. Step 7.1 and the output-verification check both read from it. A catch-all last row covers any agent that a configured type or config line names but that has no row of its own. - **The config-rule changes in `han-core/references/config-rule.md`.** These add the two new sections, a per-key precedence rule, and a second exception to "a bad config never fails a run". They also let a skill consider `## Extra Agents` on only some of its runs, which code review uses to keep the list to its default run. The file is vendored byte-identical into twelve plugins, so check that the copies match the canonical one. - **Risks worth weighing.** Typed reviews running in parallel share Step 2's automated checks in one working tree. Also, the operator decided that any focused type other than `security` runs no security check. The new `scripts/review-types.bats` checks that the type files and the type table stay consistent. Check whether it covers enough.
…e how-to Lead with a first-run path, a review-type chooser with purposes and the typed-review security caveat, and a report triage table. Move mechanism detail into In more detail and stop mirroring SKILL.md step by step. Correct facts the old page had wrong: eleven shipped types (not six), a path argument builds the file list only without git, the focus hint reaches every agent, typed reviews run one or two shipped specialists, and the validator runs only when a corrective or security finding exists.
- Say eight default-set type files, not five (Steps 1 and 3.1). - Scope the type-file YAGNI note to Step 4's Mode B and C skip. - Map High- and Medium-severity security findings to the warnings recommendation, which the template left undefined. - End a typed run's Review type line with "Security analysis did not run on this review." when its roster has no security analyst, and update the operator doc to match.
This PR proposes making the plan cross-reference checks read `###` and `####` entry headings under mawk, the default awk on Debian and Ubuntu. We include this PR work along with a full history of your repo at https://eastagiletracker.com/projects/798. You can sign in with your GitHub ID to claim ownership of the project. `check-cross-references.sh` (run by `iterative-plan-review`, SKILL.md step at line 422) and `check-plan-cross-references.sh` (run from `plan-implementation`'s `step-9-checks.md`) locate an entry's heading inside awk with the interval expression `#{2,4}`. mawk 1.3.4 20240123, which is `/usr/bin/awk` on a stock Ubuntu 24.04, matches only two hashes with that form, so the `### F1:` and `### D-1:` headings the review-findings and decision-log templates produce are never recognized. The two scripts then fail in opposite directions: a valid review pair fails with `empty-field` for every finding, and a decision log whose `Referenced in plan` names a section the plan does not have passes, because the field is never read. CI stays green because the runner's awk is gawk. Reproduced on current `main` (abba73a), Ubuntu 24.04 with its default awk: ``` $ awk -W version | head -1 mawk 1.3.4 20240123 $ printf '### F1: x\n' | awk '/^#{2,4} /{print "matched"}' (no output) $ check-cross-references.sh f.md h.md # valid pair, "### F1:" as in review-findings-template.md result: failed empty-field: F1 Raised in round empty-field: F1 Changed in plan $ check-plan-cross-references.sh plan.md log.md hist.md # "### D-1:" cites "Nonexistent Section" result: passed ``` The fix spells the level as `###?#?`, which is the same set of headings (two to four hashes, five or more still excluded) and which every awk reads the same way. Each Bats file gains a four-level heading test; both fail against the unfixed scripts under mawk and pass with the fix. `npm test` on `main` under mawk: 109 ok, 12 not ok, all in these two suites. Eleven of the twelve are this defect. With this branch: 122 ok, 1 not ok. The remaining failure, "an unreadable plan is unverified", fails the same way before and after because the run was as root, and root can read a mode-000 file. Under gawk 5.2.1 both suites give the same result before and after, so nothing changes on the platform CI uses. `prek` passes on the four changed files. ## How this was managed This fix was tracked as story https://eastagiletracker.com/projects/798/stories/1044085 on a board imported from this repo's issues and pull requests (197 stories), at https://eastagiletracker.com/projects/798.  If you'd rather not receive contributions like this, reply `no-more-prs` on this pull request and we won't open any further ones on your repositories. --- **Lawrence W. Sinclair** CEO / East Agile [linkedin.com/in/lwsinclair/](https://linkedin.com/in/lwsinclair/) [eastagile.com](https://eastagile.com)
v0.11.0.1-1 ships the same ShellCheck 0.11.0 and only raises the hook's floor to Python 3.10. prek resolves macOS's system Python 3.9, so the bump breaks lint locally while adding nothing.
## Summary Moves the dev tooling to the latest versions that work here, across the three ecosystems Dependabot tracks: npm, GitHub Actions, and pre-commit hooks. | Dependency | From | To | | --- | --- | --- | | `prettier` | 3.9.6 | 3.9.10 | | `@j178/prek` | 0.4.11 | 0.5.5 (crosses a 0.x minor) | | `bats` | ^1.11.1 | ^1.13.0 (floor raised to match the lockfile; the installed version is unchanged) | | `actions/setup-node` | v7.0.0 | v7.1.0 | The rest were already on their latest releases: `actions/checkout` v7.0.1, `actions/cache` v6.1.0, and `pre-commit-hooks` v6.0.0. **`shellcheck-py` stays on v0.11.0.1 on purpose.** The newer `v0.11.0.1-1` tag ships the same ShellCheck 0.11.0. Its only change is requiring Python 3.10 or later. prek uses macOS's system Python 3.9, so on a stock Mac the hook fails to install and `npm run lint` breaks. The branch has the bump and its revert as separate commits. **Cooldown note:** `.github/dependabot.yml` holds each new release for 30 days. Several of these are newer than that: prek 0.5.5 (Oct 5), Prettier 3.9.10 (Oct 10), and setup-node v7.1.0 (Oct 8). Merging this PR gets around the cooldown for those three. The eval scaffold `package.json` files under `evals/` are test fixtures, so they were left as they are. ## Key file changes - `package.json`, `package-lock.json`: npm devDependency upgrades. - `.github/workflows/ci.yml`: `actions/setup-node` v7.1.0 in both jobs. ## Test Plan - [x] `npm run lint` passes on every hook locally. - [x] `npm test` runs every Bats test with 0 failures. - [x] CI lint and test jobs pass on this PR.
…nd expected paths Enrich the producer so each work item carries the markers the downstream driver needs, without pulling in the driver itself: - Add a Type field (deliverable / audit / spike) and rename Tests -> Checks in the work-item template. - Add Suggested implementation, Suggested review, Requires pre-work decisions, and Expected paths fields, selected via a new deliverable-skill catalog. - Direct project-manager to derive those markers and expected paths, and close the run with the three-bucket (unattended / pauses-for-human) recommendation. - Reframe the upstream unverified-assumptions guidance onto Requires pre-work decisions, since item-level HITL/AFK moves to the per-marker model. Split out of feat/autonomous-driver-core-loop as a standalone producer-side change; carries no implement-work-items edits. Rebased onto v6.0.0-beta, resolving conflicts with the reworked skill: - The breakdown is now dispatched to plan-synthesizer, not project-manager; the new directives sit beside the Justification and drafting-order ones. - v6 removed the separate Tests block, so there is no Checks block; the audit and spike check guidance moved into Acceptance criteria. - Summary stays first; the classification fields (Type, Requires pre-work decisions, Suggested implementation/review, Expected paths) render after Acceptance criteria and before Depends on. - Catalog skill namespaces updated for skills that moved out of han-core (han-documentation, han-research). - Long-form doc changes ported to han-planning/docs/skills/plan-work-items.md; links to the not-yet-merged implement-work-items doc dropped. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-Authored-By: River Bailey <river.bailey@testdouble.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BvgX88kC9h9xbe4zGLf7BC
…nd expected paths (#226) Replaces #111 by @taminomara, rebased onto `v6.0.0-beta` to resolve its merge conflicts. The original branch lives on a fork we can't push to, so this PR carries the same commit with @taminomara kept as the commit author. All credit for the change is theirs. ## What the change does `plan-work-items` now records, for each work item, which skill or agent should build it and which should review it, and whether each part can run unattended (`AFK`) or needs a human (`HITL`). Each item also records a `Type` (`deliverable`, `audit`, or `spike`), whether it needs a human decision before work starts, and the files it is expected to touch. A new deliverable-skill catalog maps each kind of deliverable to its suggested implementation and review. ## How the conflicts were resolved The skill changed a lot on `v6.0.0-beta` since #111 was opened, so the resolution adapts the change to the new shape rather than replaying it line for line: - The breakdown is now drafted by `plan-synthesizer`, not `project-manager`. The new directives sit beside the existing justification and drafting-order directives. - `v6.0.0-beta` removed the separate `Tests` block, so there is no `Checks` block. The audit and spike check guidance moved into `Acceptance criteria`. - `Summary` stays first. The classification fields (`Type`, `Requires pre-work decisions`, `Suggested implementation`, `Suggested review`, `Expected paths`) render after `Acceptance criteria` and before `Depends on`. - Catalog skill names updated for skills that moved out of `han-core` (`han-documentation:*`, `han-research:research`). - Long-form doc changes ported to its new home, `han-planning/docs/skills/plan-work-items.md`. Links to the `implement-work-items` doc were dropped, since that skill isn't in this repo yet; `SKILL.md` still offers it only when it is available. ## Open from #111 The original PR was a draft, and @taminomara noted `audit` and `spike` were meant to merge into one type before it was ready. That is still open, so this PR is also a draft.
…ilder Checks the plugin-builder guidance against Anthropic's current pages for Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1, and Claude Code's model settings, with adversarial validation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-model guide - Widen the reasoning-echo section to every current model and list the four trigger shapes, including a reasoning field in an output format - Scope the cut-verification advice to Opus; Sonnet 5.5 and Haiku 5.5 skip checks at low effort and need the instruction kept - Add Claude Code's thinking and effort defaults for the 5.5 models - Add early-stop and scope habits for Sonnet 5.5 and Haiku 5.5 - Quote the Fable claim as Anthropic words it; fix the review-prompt attribution to the blog post Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Subagent model order is now dispatch, frontmatter, env var, main model (v2.1.251+), with CLAUDE_CODE_SUBAGENT_MODEL_FORCE to override - An omitted model is not the same as inherit - Add the fable alias; note that aliases resolve by provider - Explore now runs on the main session's model; link the live table - Note Haiku 5.5's subagent fit and its low-effort habits Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he 5.5 models - Builders' model-specific review check now flags a reasoning, thinking, or trace field, a scratchpad section, or a running reasoning log - Name model families instead of a fixed four-model list in the guidance skill, its portable copy, the rule index, and the specialization guide - Replace an unsourced Haiku claim in the testing guide with the documented Haiku 5.5 behaviors Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Move the two Anthropic links off the old docs hosts to their current platform.claude.com pages - Re-quote both Anthropic passages from the current wording; the old quotes no longer appear on either page - Say thinking depth rather than thinking budget, since budget_tokens is gone on the 5.5 models - Point the dead Deepgram link at its Wayback Machine snapshot Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
## Summary
**This PR updates the `han-plugin-builder` authoring guidance and its
two builder skills for the Claude 5.5 models (Opus 5.5, Sonnet 5.5,
Haiku 5.5, and Fable 5.1), so that new skills and agents stop carrying
instructions that current models refuse, ignore, or no longer need.**
## Behavior changes
The main runtime change is in `skill-builder` and `agent-builder`. Both
now send authors to the per-model guide (`per-model-authoring.md`)
whenever a target model comes up. Their final review (Step 6) has a new
item that catches leftovers tied to a specific model. It flags "think
step by step" lines, any request that the model reproduce its reasoning,
and output formats with a `reasoning`, `thinking`, or `trace` field, a
scratchpad section, or a running reasoning log. Every current model now
refuses that kind of request, which shows up as a `reasoning_extraction`
refusal, so the check is no longer limited to Fable 5 and Opus 5.5. The
item also flags a pinned `effort` value with no stated reason, and vague
review limits such as "only report high-severity issues." A limit passes
when it names a bar the reader could check and asks for evidence on each
item.
Two existing review items are stricter. `agent-builder` now requires a
research or analysis agent to mark each claim it could not confirm and
say where it looked. `skill-builder` now counts an instruction that
restates something the model already does by default as removable.
The rest of the branch is guidance text that the builders and
`/guidance` read:
- **Per-model facts.** Advice to cut verification instructions applies
only to Opus. Sonnet 5.5 and Haiku 5.5 skip checks at low effort.
- **Subagent model choice.** The order Claude Code uses to pick a
subagent's model changed in v2.1.251. Explore no longer runs on Haiku.
- **Long runs and fan-out.** New patterns for unattended work and for
fanning work out to subagents.
- **Other new sections.** Verification skills, where skill state lives
(`${CLAUDE_PLUGIN_DATA}`), helper-script libraries, and hooks scoped to
one skill's run.
All model facts come from Anthropic's own docs, checked 2026-10-15. The
planning and research behind each change are in
`docs/plans/opus-5-5-plugin-builder-guidance/`. Repos that vendored this
guidance with `/guidance init` get it on `/guidance update`, so mention
that in the release notes. The branch also carries one unrelated note,
`docs/plans/fix-ci-lint-evals-prettier/investigation.md`, which
investigates a CI lint failure.
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)
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
4 participants
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: