| name | invowk-typesystem |
| description | Invowk type-system and goplint guidance for value types across cmd/*, internal/*, and pkg/*, including Validate() contracts, primitive-wrapper value objects, aliases/re-exports, sentinel errors, Invalid*Error wrappers, check-types/check-types-all findings, DDD compliance, and baseline updates. Use when adding, reviewing, refactoring, or documenting value types. |
| metadata | {"short-description":"Canonical operating guide for Invowk's value-type architecture.","ownership":"Repo-wide type-system conventions and catalogs","audience":["Agents implementing new domain/value types","Agents reviewing Validate()/error-shape consistency","Agents documenting type-system changes"],"trigger-patterns":["value type","Validate","ErrInvalid","Invalid*Error","primitive wrapper","typesystem","DDD type","type safety","goplint baseline type findings"],"scope":{"includes":["cmd/**","pkg/**","internal/**"],"excludes":["generated files","non-Go docs unless explicitly requested"]},"outputs":["Type-system impact analysis","Updated value-type catalogs","Validation and guardrail checklist"],"maintenance":{"source-of-truth":"references/type-catalog.md","refresh-script":"scripts/extract_value_types.sh","refresh-trigger":"Any addition/removal/rename/semantic change of a value type"}} |
Invowk Typesystem
Use this skill when:
- Creating or refactoring value types in
cmd/*, pkg/*, or internal/*
- Debugging
Validate() behavior, sentinel error wrapping, or Invalid*Error shapes
- Resolving goplint findings related to primitive wrappers, DDD compliance, and type safety
- Documenting type-system changes for agent guidance
Mandatory Workflow
- Read
references/value-type-patterns.md to apply canonical design rules.
- Check
references/type-catalog.md before introducing a new type.
- If a new type is still needed, follow the creation checklist in
references/maintenance-workflow.md.
- Refresh the catalog with
scripts/extract_value_types.sh and reconcile the docs.
- Run the required checks listed below.
Canonical Value-Type Contract
Invowk value types should follow this contract unless a domain-specific exception is justified:
- A dedicated type (prefer primitive wrapper where possible) with domain intent in the name.
- A sentinel error variable, usually
ErrInvalid<Type>.
- A typed error struct, usually
Invalid<Type>Error, that wraps the sentinel via Unwrap().
Validate() error for programmatic validation.
String() for wrappers where string rendering is used operationally.
Reference implementation patterns are in references/value-type-patterns.md.
References
-
references/type-catalog.md
Comprehensive catalog of all current value types, including:
- all types implementing
Validate() error
- all primitive-wrapper value objects
- alias/re-export type mappings
-
references/value-type-patterns.md
Design patterns, naming/error conventions, goplint directives, and anti-patterns.
-
references/maintenance-workflow.md
Update protocol, verification commands, and drift-prevention checks.
Required Checks After Typesystem Changes
make check-baseline
make check-types for targeted DDD checks when production type shapes changed
make check-types-all / make check-types-all-json for broad type-system sweeps
make test
make lint
make check-file-length
make check-agent-docs (if AGENTS.md or .agents/skills/* changed)
For docs-only type-catalog refreshes, use at minimum: