Repository navigation
Feature: a framework for user overrides to han integration points and skills #112
Description
Idea
Introduce a framework for customizing han's behavior beyond custom instructions in CLAUDE.md.
Right now, the only way to customize han is by writing custom instructions into CLAUDE.md. Writing voice is baked directly into skills, and the work-item-to-skill routing being added in #111 has no way to take user-supplied direction. Han could benefit from a shared format mechanism for providing overrides to known integration points and skills.
Two concrete examples of where this would plug in:
- feat(plan-work-items): classify each item's implementation, review, and expected paths #111 routing. The routing agent could resolve additional user instructions by looking for a specifically named file.
- Writing voice. A skill that applies writing voice could use a user-provided override instead of the built-in writing voice when one is present.
Open questions
These are the decisions a feature spec would need to resolve:
- Coverage. Which integration points and skills should the mechanism cover: only the two examples above, or every skill and agent with a known integration point?
- Format and discovery. What does an override look like, where do override files live, and how does an agent find them (naming convention, location, file structure)?
- Precedence. Does an override replace or augment the built-in behavior, and how does a partial override behave against the built-in default?
- Success criteria. What must a user be able to override, and how do they confirm an override took effect?
Suspected areas
- Writing-voice application across skills (
docs/writing-voice.mdis the canonical voice profile every doc and skill follows). - The work-item-to-skill routing integration point introduced by feat(plan-work-items): classify each item's implementation, review, and expected paths #111.
- The skill and agent instruction-resolution path, where a named override file would be discovered and merged with built-in behavior.
Suggested next step
Route to /plan-a-feature: the direction (build an override mechanism) is chosen and the job-to-be-done is clear, but the mechanism is not yet specified.
Activity
mxriverlynn commentedon Jul 10, 2026
i've been thinking about this for a while, as well! glad to see this put in here as a triaged issue 🙂
mxriverlynn commentedon Jul 10, 2026
some random(ish) thoughts:
.han/folder where config and overrides could live.han/branch-contextfolder that could easily be ignored in a.gitignorefile would be a great way to handle this (more details to come in a PR at some point, for that skill)taminomara commentedon Jul 10, 2026
Would be nice to have, although not necessary: a
!`-embedded resolver that walks up the directory tree searching for.handirectory. We have a ton of repositories, and a tool that provisions VMs, sets up Claude Code plugins, and clones everything needed for a task. Having a single.hanin home directory would spare us from committing the same files into every repo. But we can, of course, just symlink it into each repo root, so this is not a hard requirement.mxriverlynn commentedon Jul 30, 2026
i forgot this issue ticket existed 😅 - FYI, though, this is largely implemented in the v5 alpha branch / build (#130). i'll do another pass on this ticket to make sure i got all the bits that were outlined here, though