What is a pattern in this skill?

A documented recurring structure, abstraction, or approach with rationale and code examples that guide how to implement, design, verify, or review the project.

How do I find relevant patterns?

Consult the dense index at .claude/rules/patterns.md for one-line summaries and pointers to full pattern files, then read the specific pattern you need.

When can I deviate from a pattern?

Only with a good reason; document the rationale for deviations to help future reviews.

patterns

Scanned

npx machina-cli add skill nklisch/skilltap/patterns --openclaw

Files (1)

SKILL.md

4.4 KB

Project Patterns Reference

This skill contains documented code patterns for this project — recurring structures, shared abstractions, and architectural approaches that keep the codebase consistent.

Each pattern file has a rationale explaining why the pattern exists, concrete code examples with file references, and guidance on when to use it (and when not to).

How to Use

When writing new code or reviewing changes, check if an established pattern applies. If it does, follow it. If you have a good reason to deviate, note why.

The dense index at .claude/rules/patterns.md loads automatically and provides one-line summaries with pointers to full pattern files. Read the individual pattern file when you need full details.

Available Patterns

Core Architecture

result-type.md — Result<T,E> discriminated union with ok()/err() constructors for railway-oriented error handling across all core functions
error-hierarchy.md — SkilltapError base class with typed subclasses (UserError, GitError, ScanError, NetworkError) and optional hint field
zod-boundary.md — Zod schema as single source of truth for types + validation; safeParse + z.prettifyError at every data boundary; .prefault({}) for nested defaults
config-io.md — Config/state load-save algorithm: ensureDirs → exists check → read → parse → Zod validate → Result

Adapter Patterns

source-adapter.md — SourceAdapter strategy pattern: plain object literals with canHandle() + resolve(), iterated by a priority-ordered resolver
agent-adapter-strategy.md — AgentAdapter interface with detect()/invoke(), factory functions for CLI/custom/Ollama adapters, three-priority resolution via resolveAgent()

Command Patterns

callback-driven-options.md — Core functions accept typed option objects with async callbacks for decision points; omitting callback = auto-proceed; 10+ callback fields across InstallOptions/UpdateOptions
policy-composition.md — composePolicy(config, flags) pure function centralizes all config + CLI flag precedence into EffectivePolicy; used for early command branching
agent-mode-branching.md — CLI commands fork into runAgentMode() (plain text, auto-accept, hard-fail) vs runInteractiveMode() (spinners, prompts, ANSI) based on policy

Git & Security

bun-shell-git.md — All git operations via wrapGit<T>() wrapper + Bun's $ template tag with .quiet(); extractStderr() for consistent error extraction
security-detector-composition.md — 7 independent detector functions composed in a for-loop inside scanStatic(); StaticWarning extends PatternMatch with a file field
install-result-with-warnings.md — installSkill() returns InstallResult { records, warnings, semanticWarnings }; optional callbacks for per-skill interception; skipScan: true in tests

Testing

test-fixtures.md — Fixture repo factories: createX() returns { path, cleanup }; copies static fixtures, initializes git repo, commits; always dot:true in Bun.Glob.scan
test-result-assertions.md — Result assertion pattern: expect(result.ok).toBe(true) + discriminated union guard; VALID_* constants with spread for schema test variants
cli-subprocess-testing.md — CLI integration tests use Bun.spawn with SKILLTAP_HOME/XDG_CONFIG_HOME env vars for isolation; stdin: "pipe" for non-TTY detection tests

Trust & Source Handling

injectable-dependencies.md — Core functions with external I/O accept _dep = realImpl optional params; tests inject mocks as 2nd/3rd args; private type Fn = typeof realFn aliases enforce signature compatibility
graceful-fallback-chain.md — Optional verifiers return T | null not Result; caller cascades through priority tiers (provenance → publisher → curated → unverified); outer try/catch guarantees a valid result always
adapter-driven-branching.md — resolved.adapter from resolveSource() gates source-type-specific logic (npm vs git vs local) throughout install, update, and trust flows

Source

git clone https://github.com/nklisch/skilltap/blob/main/.agents/skills/patterns/SKILL.mdView on GitHub

Overview

Project Patterns Reference documents recurring structures, shared abstractions, and architectural approaches that keep the codebase consistent. It provides rationale, code examples with file references, and guidance on when to use each pattern. The dense index at .claude/rules/patterns.md auto-loads and ties patterns to real files.

How This Skill Works

Patterns are stored as individual files with rationale, examples, and usage guidance. The system auto-loads them into the skill context when implementing, designing, verifying, or reviewing code, and a dense index points to full pattern details and file references for deeper exploration.

When to Use It

When starting new code or making changes, check for applicable patterns.
When reviewing contributions to ensure consistency with project conventions.
When trying to understand how the project structures things via pattern files.
When designing architecture that should follow established patterns.
When you need concrete code examples and pointers to full pattern details.

Quick Start

Step 1: Open the dense index at .claude/rules/patterns.md to see available patterns and summaries.
Step 2: Open a specific pattern file (e.g., Core Architecture/result-type.md) to read the rationale, code examples, and usage guidance.
Step 3: Apply the pattern to your code and reference the pattern file for full details and edge cases.

Best Practices

Consult the dense index at .claude/rules/patterns.md for summaries and links to the full pattern files.
Follow established patterns unless you have a well-justified reason to deviate, and note why.
Read the rationale and see the concrete code examples in the chosen pattern file before applying it.
Reference the specific pattern file for file references and usage context.
Document any deviations with clear rationale to aid future reviews.

Example Use Cases

Core Architecture: use result-type.md — Result<T,E> with ok()/err() across core functions for railway-oriented error handling.
Data boundaries: apply zod-boundary.md to enforce a single source of truth for types and validation with safeParse and prettified errors.
Adapters: implement source-adapter.md as a Strategy with canHandle()/resolve() and a priority-resolved list.
Git & Security: wrapGit usage via bun-shell-git.md for consistent error extraction and quiet command execution.
Testing: leverage test-fixtures.md and test-result-assertions.md for robust fixture-based tests and discriminated union checks.

Frequently Asked Questions

Add this skill to your agents