quirk

Core skills library for Claude Code: TDD, debugging, collaboration patterns, typed artifacts, and proven techniques.

Version: 2026.7.9

What ships

• 24 skills under skills/ covering TDD, systematic debugging, brainstorming (which produces a logic spec), deep-research/brainstorming exploration (with a --involve user-inclusion dial: checkpoints, mid-run steering, and idea-gate co-creation), divergent ideation, tech-spec authoring and plan writing, scannable-prose revision, code review, adversarial review (typed profiles, a promote/refute two-stage, and an evidence gate), parallel agent dispatch, guided bug/feature/code-change filing with provenance-marked artifacts, and more.
• Typed artifacts (added in 5.1.0) — surface-routing for observations Claude cannot act on. See below.

Installation

Install via the quirk-dev marketplace (.claude-plugin/marketplace.json).

Typed artifacts

A discipline for routing deferred observations into structured markdown files instead of burying them in prose ("pre-existing", "out of scope", "skipped for brevity").

Quick start

In your project, run:

/quirk:artifacts:init

That scaffolds BUGS.md, DEFERRED.md, TEST_BACKLOG.md, proposals.md, and docs/adr/. It also appends a 5-line trigger snippet to your project's CLAUDE.md (use --no-claude-md to skip that).

Slash commands

Command	Purpose
/quirk:artifacts:init	Scaffold artifact files into the current project
/quirk:artifacts:bug	Append a BUG-N entry to BUGS.md
/quirk:artifacts:defer	Append a DEFER-N entry to DEFERRED.md
/quirk:artifacts:test-skip	Append a TEST-N entry to TEST_BACKLOG.md
/quirk:artifacts:triage	Classify an observation and append to the right file
/quirk:artifacts:adr	Create a new Architecture Decision Record
/quirk:artifacts:review-artifacts	Read-only summary of all entries

Hooks

Three lifecycle hooks (warn-only, never block):

• SessionStart loads tail of artifact files (or suggests /init if none exist).
• PostToolUse lints written files for tic phrases ("pre-existing", etc.).
• Stop posts a wrap-up reminder.

All three gate on artifact-file presence — they are inert no-ops in projects that haven't run /quirk:artifacts:init.

Logic spec + tech spec

See docs/specs/2026-05-04-typed-artifacts-design.md (historical, pre-restructure). Current specs live under a per-topic folder: docs/quirk/specs/YYYY-MM-DD-<topic>/logic.md (always) and docs/quirk/specs/YYYY-MM-DD-<topic>/tech.md (only when warranted).

Agent Isles bridge

Quirk can author Agent Isles-aware artifacts while keeping Markdown canonical and Agent Isles optional. The stdlib-only helper in bin/agent_isles.py detects a local isles binary, an isles on PATH, or an explicit npx agent-isles@next fallback; it never silently installs packages.

python3 bin/agent_isles.py doctor
python3 bin/agent_isles.py command examples/agent-isles/typed-artifacts-summary.md

The experimental local component pack lives in packs/quirk/ and covers typed artifact summaries, TDD cycle reports, plan readiness, and review findings. Examples live in examples/agent-isles/. See docs/agent-isles-artifacts.md for the authoring contract: Markdown source is canonical, generated HTML under .quirk/isles/ is disposable by default, and the Quirk pack is trusted local code.

Development

python3 -m pytest -q

Stdlib-only Python 3.9+. No third-party dependencies.