日本語版: README.ja.md

kamae-ts

Kamae (構え) — a stance of readiness.

An extensible harness of skill plugins for designing and implementing robust server-side TypeScript applications. Each skill encodes a kamae — a practiced stance for a specific design concern — that coding agents apply when generating or reviewing code.

The current stances focus on functional domain modeling; more will be added over time.

Overview of Principles

  • Represent domain state with Discriminated Unions, avoiding classes
  • Define state transitions with pure functions, making invalid transitions compile errors
  • Handle errors as values with Result types (neverthrow / byethrow / fp-ts / option-t), avoiding thrown exceptions
  • Validate external boundaries with schema validation (Zod / Valibot / ArkType), trusting types inside the domain
  • Protect PII at runtime with the Sensitive type

Installation

Via gh skill (the GitHub CLI's agent skills extension):

# Install a single skill (interactive prompt for agent/scope)
gh skill install iwasa-kosui/kamae-ts kamae

# Install non-interactively for Claude Code at user scope
gh skill install iwasa-kosui/kamae-ts kamae \
  --agent claude-code --scope user

# Pin to a specific release
gh skill install iwasa-kosui/kamae-ts [email protected]

Or via skills CLI:

npx skills add iwasa-kosui/kamae-ts

Provided Skills

kamae

Triggered when writing server-side TypeScript code (domain models, use cases, repositories, state transitions, error handling, boundary validation, PII protection). Guides code generation through a thin dispatcher SKILL.md that lazy-loads topic sub-files (domain-modeling.md, state-modeling.md, error-handling.md, boundary-defense.md, declarative-style.md, test-data.md) and library-specific guides only when relevant.

kamae-review

Triggered during code review. Walks a checklist of severity-tagged review items (split across checklist/*.md sub-files) and reports findings citing the canonical principle in kamae. Depends on kamae being installed for the knowledge base — install both together.

Customization via Rules

Both skills load applicable rules at the start of each invocation, in priority order:

  1. .claude/rules/*.md (project)
  2. ~/.claude/rules/*.md (user-global)
  3. The plugin's own rules/defaults/*.md

A rule applies to kamae-ts when its frontmatter declares applies-to: kamae, applies-to: kamae-review, or applies-to: "*". Four rule types are supported:

  • library-preference — pin a specific Result or validation library (overrides auto-detection)
  • check-toggle — disable a named review check (e.g., PII protection for projects with no personal data)
  • convention — declare project-specific conventions (e.g., "Branded Types live in src/types/brand.ts")
  • override — replace specific guidance from a topic sub-file

See rules/README.md for the rule format and concrete examples.

For full skill replacement, use Claude Code's standard skill path-shadowing (.claude/skills/kamae/SKILL.md overrides the installed plugin's).

Evaluation

Skill quality is continuously evaluated with microsoft/waza.

Documentation

A reading version of the principles is published at https://iwasa-kosui.github.io/kamae-ts/, in both English (/en/) and Japanese (/ja/).

Community

Join the official Discord server to discuss server-side TypeScript, ask questions, and share what you are working on: https://discord.gg/Z9HVbqEWzd

  • See the community page for channel layout and what kind of conversation happens there.
  • Both this GitHub repository and the Discord server are governed by the Code of Conduct (Contributor Covenant v2.1).

Reference Articles

These principles are based on the following articles:

License

MIT