add skill: /han-coding:design-an-api - #175
Merged
Merged
Conversation
Closes #173. Adds /design-an-api, which designs an interface contract for one stated goal: a discovery wave, an options document from the software architect, a user option pick, a junior-developer question round, open items surfaced one at a time, and an adversarial validation round. Every element of the contract carries a justification naming the goal language it descends from or the behavior it is a necessity of; anything that cannot fill that field lands on a cut list the user sees. Also closes the two-way disambiguation gaps against architectural-analysis, plan-a-feature, and plan-implementation.
…w fixes Adds the long-form doc, the plugin README scent line, the skills index entry, the workflows chain, and the CLAUDE.md map entries. Review fixes against the plugin-building guidance: a testable git criterion for the starting-point question, error handling for a failed discovery agent and a single-option architect round, explicit continuation after each mid-workflow skill invocation, and a boundary-data signal replacing the unfamiliar-area signal that had no consumer now that codebase-explorer runs at every band.
…ure paths Two defects made the skill's own rules contradict each other. The ordering signal matched both the Small band (which said it "may be present or absent") and the Medium band (which counted it among the five escalating signals), and because the concurrency analyst carries a Medium minimum, the signal could fire at small with no specialist able to answer it. The roster listed the architect as running in Steps 5, 7, and 9, omitting the Step 8 relaunch that folds in the open-item answers. The starting-point check ran `git diff $(git merge-base HEAD origin/HEAD)...HEAD`. When origin/HEAD is unset the substitution empties, git reads the rest as HEAD...HEAD, and the command exits clean with no output, so a branch that did modify the interface was reported as untouched. It now reads the same default-branch probe the other Han skills use and treats `unknown` explicitly. Also: the overwrite guard covered only api-design.md, leaving the context brief and options document to be silently overwritten; Step 5 retried the architect for missing justifications but had no disposition when the retry also came back unjustified; Step 8 had no path for zero open items; and the roster caps were written as ranges whose floors the rules cannot produce, since a large band reached by a lone system-seam signal dispatches five agents, not seven.
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
1 participant
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.
closes #173
Summary
This PR adds a
/design-an-apiskill tohan-codingthat designs an interface contract against one stated goal, so you settle a surface's shape before implementation instead of discovering it while writing the code.Behavior changes
The skill's load-bearing rule is that every element of the contract has to justify itself. Each parameter, field, type, default, precedence rule, and failure behavior must trace to one of two sources. It either descends from a specific part of the stated goal, or it is necessary for an asked-for behavior. Anything that fits neither source stays out of the design. It lands on a cut list you can see and reinstate, and your direction then becomes its justification. The skill also refuses to run without a goal, because a goal is what stops a contract for one caller from growing into a general-purpose framework. Silence in the goal is not treated as a cut, so error behavior and types survive even when the ticket never mentions them.
A run classifies the interface's size by grepping the code for signals: consumer spread, ordering, persisted or wire data, untrusted input, failure paths, cross-module data, and cross-service seams. It defaults to small and escalates only when one of those signals is clearly present. Four core agents run at every size, and a specialist joins only when its signal is present. From there you hit two gates: first you pick one of two or three real options the architect presents, then you answer any remaining open items one question at a time. An adversarial validation round attacks the amended design before the document is rendered. The run writes three markdown files (context brief, options, final design), date-suffixes rather than overwriting existing ones, and changes no code. That final document is the input to a later
/tddrun.Three existing skills change only their routing text.
architectural-analysis,plan-a-feature, andplan-implementationnow namedesign-an-apiin their "not for this" lines. A request to design an interface now routes to the new skill, not to a skill that judges existing structure, specifies behavior, or sequences delivery.