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; 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.