Boundary definition

Skill zoidbergclawd/coherence/skills/boundary-definition

Five portable Agent Skills for Claude Code that keep humans and coding agents aligned at high velocity.

Install

npx -y skills add zoidbergclawd/coherence --skill boundary-definition

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when starting a feature, refactor, integration, API change, or state-machine change, before writing code, to force explicit interfaces, inputs, outputs, contracts, invariants, ownership, non-goals, and failure modes.

SKILL.md

4.3 KB, as published. Nobody here has run it

Boundary Definition

When to use this skill

Starting a new feature, module, or component
Refactoring across module boundaries
Adding to or changing an API surface
Modifying a state machine or shared protocol
Touching code where ambiguity could become architecture
Connecting two systems that have not been connected before

If unsure whether the work qualifies, run this skill anyway. The cost of a 5-minute spec is lower than the cost of an incoherent boundary.

Core principle

Ambiguity at the boundary becomes architecture. The boundary is the agreement between callers; the implementation is the consequence. Define the agreement first, in writing, with no implicit assumptions. If a field cannot be answered concretely, that field is the work.

Procedure

Do not code yet. Open a scratch document or comment block.
Fill in the Boundary Spec template below for each new or changed unit. One spec per unit, not one spec for the whole feature.
Read the spec back. Each field must be answerable in one sentence. Vague answers indicate hidden ambiguity — rewrite, do not paper over.
Stop and resolve any item in Open questions with the user before continuing.
If the work is non-trivial, hand the completed spec to multi-pass-planning as the input to the Plan pass.
Keep the spec in the repo (e.g. docs/specs/<name>.md or alongside the module) so future sessions can reload it without rederiving.

Boundary Spec template

Boundary Spec: <name>
- Owner: which module and which person/agent owns this surface
- Purpose: one sentence, in user-visible terms
- Inputs: types, ranges, units, who supplies them, trust level
- Outputs: types, ranges, success shape, failure shape
- Preconditions: what must be true before the unit is invoked
- Postconditions: what must be true after a successful invocation
- Invariants: what must remain true throughout, including on failure
- Failure modes: enumerated. For each: how it surfaces, who handles it
- Side effects: I/O, state mutation, network, time, randomness
- Non-goals: what this explicitly does not do
- Compatibility: existing callers, what breaks if the shape changes
- Open questions: items the agent cannot answer without the user

Required output format

A markdown block titled Boundary Spec: <name> containing every field above, in order, with concrete one-sentence answers. The block must end with an Open questions list. If that list is non-empty, the agent stops and asks the user before proceeding.

Stop conditions / escalation triggers

Any field cannot be answered concretely — escalate to the user
Failure modes is empty — failure has not been thought through; do not proceed
Non-goals is empty — scope is unbounded; do not proceed
Multiple owners claim the same boundary — resolve ownership first
Caller list is unknown for a public-shape change — search the codebase or ask
The spec contradicts an existing spec for a neighboring boundary

Short examples

Good (TypeScript config parser):

Boundary Spec: parseConfig
- Owner: src/config (module), team: platform
- Purpose: Convert untrusted JSON into a validated Config or a typed error.
- Inputs: unknown JSON value; schemaVersion: "1" | "2".
- Outputs: Result<Config, ConfigError>.
- Preconditions: schemaVersion is one of the supported versions.
- Postconditions: returned Config has all required fields populated.
- Invariants: never throws; all errors flow through ConfigError.
- Failure modes:
    - InvalidShape -> caller logs and exits non-zero
    - UnsupportedVersion -> caller prompts user to upgrade
- Side effects: none.
- Non-goals: does not read disk; does not migrate v1 configs to v2.
- Compatibility: callers in src/cli and src/server; both consume Result.
- Open questions: none.

Bad (rejected, rewrite):

Boundary Spec: parseConfig
- Inputs: any JSON.
- Outputs: a Config.
- Failure modes: throws on bad input.

This hides input trust level, the failure taxonomy, and the contract for callers. Every reader will fill the gaps differently — that is how incoherent architecture is born.