git:20260510.19d9411 to git:20260712.e2f8077

- description: "Project code patterns and conventions. Auto-loads when implementing,

- designing, verifying, or reviewing code. Provides detailed pattern definitions

- with code examples. Consult this whenever writing new code, reviewing changes,

- or trying to understand how this project structures things."

- 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; `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<T>` 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<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, 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.