# Patterns

> Project code patterns and conventions. Auto-loads when implementing,

- **Type:** Skill
- **Install:** `agentstack add skill-nklisch-skilltap-patterns`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nklisch](https://agentstack.voostack.com/s/nklisch)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nklisch](https://github.com/nklisch)
- **Source:** https://github.com/nklisch/skilltap/tree/main/.agents/skills/patterns
- **Website:** https://skilltap.dev/

## Install

```sh
agentstack add skill-nklisch-skilltap-patterns
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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` 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; `parseWithResult()` helper
- **config-io.md** — Config/state load-save algorithm: ensureDirs → exists check → read → parse → Zod validate → Result; state.json uses `loadState`/`saveState`
- **json-state-io.md** — `loadJsonState` and `saveJsonState` generic helpers; all state modules delegate to these, no ad-hoc JSON I/O

### 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()`
- **adapter-driven-branching.md** — `resolved.adapter` from `resolveSource()` gates source-type-specific logic (npm vs git vs local) throughout install, update, and trust flows

### Command Patterns
- **output-interface.md** — `setupOutput(args)` → `Output` handle; 3 modes (tty/plain/json); all command output goes through `out.*` methods; replaces old agent-mode-branching split
- **callback-driven-options.md** — Core functions accept typed option objects with async callbacks for decision points; omitting callback = auto-proceed; `out?: Output` for progress
- **policy-composition.md** — `composePolicy(config, flags)` → `EffectivePolicy`; `composePolicyForSource` adds trust overlay; `loadPolicyOrExit()` is CLI-layer entry point
- **scope-base.md** — `scopeBase(scope, projectRoot?)` pure helper — single-source scope-to-base-dir; use derived helpers (`skillInstallDir`, etc.) for full paths

### State Management
- **apply-state-change.md** — `applySkillStateChange({scope, projectRoot, mutate, manifestSync?})` atomic load→mutate→save for skills[]; fires manifest sync hooks on diff

### Git & Security
- **bun-shell-git.md** — All git operations via `wrapGit()` 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, updates, pluginRecord? }`; unified `onWarnings(warnings, kind, name)` callback

### 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
- **test-env-isolation.md** — `createTestEnv()` from `@skilltap/test-utils` returns `{ homeDir, configDir, cleanup() }`; replaces per-test manual env save/restore
- **cli-subprocess-testing.md** — Use `runSkilltap(args, homeDir, configDir)` + `cliCmd()` from `@skilltap/test-utils`; routes to compiled binary when `SKILLTAP_TEST_BIN` set

### 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
- **single-source-definitions.md** — One authoritative constant per enumerable concept; agent metadata in `symlink.ts`; config enum arrays in `schemas/config.ts`

### Deprecated / Removed
- **agent-mode-branching.md** — ⚠️ REMOVED. `policy.agentMode` and `runAgentMode()`/`runInteractiveMode()` no longer exist. See output-interface.md.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nklisch](https://github.com/nklisch)
- **Source:** [nklisch/skilltap](https://github.com/nklisch/skilltap)
- **License:** MIT
- **Homepage:** https://skilltap.dev/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nklisch-skilltap-patterns
- Seller: https://agentstack.voostack.com/s/nklisch
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.