pi-effect-harness

Table of contents

• What it does
• Install
• Usage
• How it works
  • Lifecycle
  • The skill gate
  • The policy header
  • The pattern feedback loop
  • The reference clone
• Skill catalog (41)
• Pattern catalog (46)
• Configuration
• Caveats
• Development
• License

---

What it does

When /toggle-effect-harness mode is enabled in the active Pi session:

• A gold effect badge appears in the Pi footer; mode state persists per-project.
• The system prompt is augmented every turn with effect-first-development.md (40+ rules covering errors, schemas, layers, services, retries, timeouts, structured concurrency, and observability), a progressive-disclosure agent rules doc, and a "loaded N/5 effect-* skills on this branch" preview.
• Tool calls that would write Effect code are blocked until at least 5 effect-* skills have been read on the active branch. The check uses a prospective write projection: it looks at the resulting file, so deletion-only changes that leave no Effect code are not blocked.
• After every successful write, the post-write file is matched against 46 pattern detectors. Matches are sorted by severity and replied back to the agent in-band as a single user message — including the pattern's transformation guidance and a hint to load any suggested skills.
• A shallow clone of Effect-TS/effect-smol is maintained at ~/.cache/effect-v4/ and refreshed to the latest Effect v4 beta source. The agent reads from this shared user cache to verify v4 APIs instead of guessing.

Everything else about your Pi session is unchanged. Toggle /toggle-effect-harness off and the harness disengages cleanly — the system prompt reverts on the next turn, the gate stops firing, and the pattern loop stops emitting feedback.

---

Install

pi install npm:pi-effect-harness

This registers the extension and all 41 effect-* skills via the package's pi manifest. Pi auto-loads on the next session start.

The first time you enable /toggle-effect-harness, the harness creates a shared user-level effect-smol clone at ~/.cache/effect-v4/ (≈30s, shallow, fail-silent). Later sessions reuse that single cache and refresh it to the latest Effect v4 beta source.

---

Usage

Toggle	/toggle-effect-harness (interactive), or Tab then E via Pi's mode toggle UI
Status	Gold effect badge in the footer
Persistence	Project-scoped Pi session state; survives session restart
Skill metrics	/effect-skill-stats [--since 30d] [--json]
Activation cost	First time per user cache: shallow clone of effect-smol; later enabled turns do a shallow refresh
Per-turn cost	~3 KB of system-prompt headers + the merged guidance docs

When mode is off, no policy header is injected and no write gate or pattern feedback fires. The harness may still rebuild its command/skill catalog and record successful effect-* skill reads as invisible branch metadata and as append-only usage metrics, so the loaded-skill count and /effect-skill-stats report are ready if you re-enable the mode later.

---

How it works

The harness is a thin shell around an Effect ManagedRuntime. Pi events are forwarded to a HarnessController, which fans them out to a RuleSet and a HookSet. Rules return Decision values; a DecisionExecutor translates those decisions back into Pi ExtensionAPI calls.

Lifecycle

session_start ─► restore mode state · clear pending skill reads · rebuild SkillCatalog
              · ensure ReferenceClone if enabled

session_tree  ─► sync mode badge · clear pending skill reads · rebuild SkillCatalog

before_agent_start
  ├─► HookSet
  │     └─► EnsureReferenceClone (if enabled, refresh shared user cache)
  └─► RuleSet
        └─► InjectEffectPolicyHeader
              └─► Decision.InjectSystemPrompt

tool_call
  ├─► HookSet
  │     └─► TrackSkillRead (Read paths matching effect-* skills)
  │           └─► PendingSkillReads.remember(toolCallId, skillName)
  └─► RuleSet
        └─► RequireLoadedSkillsForEffectWrites
              ├─► WriteProjection.prospective(cwd, writeIntent)
              └─► Decision.BlockToolCall  (if Effect code present and skills < 5)

tool_result
  ├─► HookSet
  │     └─► EmitSkillLoadedEntry (successful tracked skill reads)
  │           └─► Decision.AppendCustomEntry
  │                 (customType: "pi-effect-harness:skill-loaded")
  └─► RuleSet
        └─► SendPatternFeedbackAfterWrite
              ├─► WriteProjection.actual(cwd, writeIntent)
              ├─► PatternMatcher × 46 patterns
              └─► Decision.InjectUserMessage

session_shutdown ─► unregister mode badge

Three rules plus session/tool hooks. Session hooks keep the skill catalog and shared reference clone current; tool events record skill reads and run write checks. Successful skill reads are written both to invisible session entries (pi-effect-harness:skill-read) and to ~/.pi/agent/pi-effect-harness/skill-reads.jsonl for aggregate reporting. Everything that touches Pi from rule/hook code runs through Decision; global metrics are handled by the telemetry service.

The skill gate

Effect v4 is wide. A model writing Effect cold — without any in-context skill — will reliably produce v3 patterns: Effect.catchAll, Schema.parseJson, Data.TaggedError, OptionFromSelf, compose(...) instead of decodeTo(...), untraced Effect.gen everywhere. The skill gate exists to make the agent stop and read before writing.

What counts as a skill. Each subdirectory under skills/ has a SKILL.md with frontmatter. Pi exposes these as /skill:effect-error-handling commands. The harness watches every successful Read tool call: when the read path resolves to a known effect-* skill (matched against the live skill catalog), it remembers the pending read keyed by toolCallId. On tool_result, if the read succeeded, it appends an invisible branch-metadata entry shaped like:

{
	customType: "pi-effect-harness:skill-loaded",
	data: {
		name: "effect-error-handling",
		path: "/absolute/path/to/effect-error-handling/SKILL.md"
	}
}

What "loaded" means. Loaded-skill state is derived, not stored. The activeBranchLoadedEffectSkills atom scans the current branch's entries for those custom entries and returns the resulting ReadonlySet<string>. This means:

• /compact, /fork, and /clone reset the count by default — re-loading skills after a context reset is a feature, not a bug.
• The count is monotonic within a branch.
• Counting pending reads in addition to confirmed loads avoids a race where the gate fires between the Read tool call and its result.

The threshold. MIN_EFFECT_SKILLS = 5. Schema, Error Handling, and Layers cover ~70% of any Effect codebase; the remaining two should be task-relevant (AI, SQL, HTTP, CLI, RPC, Workflow, Stream, Testing, Observability, etc.). Five is calibrated, not arbitrary — fewer and the model still hallucinates; more and the activation friction outweighs the benefit.

Why prospective projection matters. The gate runs on WriteProjection.prospective(cwd, writeIntent), which reconstructs what the file will look like after the write/edit applies. A change whose resulting file no longer matches \bEffect\b|from\s+['"]effect.*['"] is allowed through. A change whose resulting file contains Effect code is gated. This means deletion-only Effect cleanup can proceed without artificially incrementing the skill counter.

The block message quotes the loaded count, the missing count, and a hint to read from ~/.cache/effect-v4/ if any API is unclear. The agent retries after loading more skills.

Skill read metrics. Every successful read of a known effect-* skill is also recorded as a pi-effect-harness:skill-read session entry and appended to the global metrics log at ~/.pi/agent/pi-effect-harness/skill-reads.jsonl. Explicit /skill:effect-* commands are recorded as source: "skill-command". Run /effect-skill-stats, optionally with --since 30d or --json, to see most-read skills, least-read skills, skills read at least once, rare skills, and neglected skills from the current live skill catalog.

Use this when reviewing skill coverage. For example, if a future session asks "what are the least used Effect skills?", run /effect-skill-stats and inspect the Least-read skills, Rare skills, and Neglected skills sections. --since 30d limits the window; --json returns the same summary data for ad-hoc sorting or deeper analysis.

From a source checkout, you can seed the global log from historical Pi sessions with bun run backfill:effect-skills --write. The backfill scans ~/.pi/agent/sessions/**/*.jsonl, pairs assistant read tool calls with successful toolResult entries by toolCallId, matches only paths under skills/effect-*, skips tool-call records already present in the global log, and does not mutate old session files. Run without --write for a dry run.

The policy header

Every turn while mode is enabled, InjectEffectPolicyHeader emits a Decision.InjectSystemPrompt whose content is the merged contents of harnesses/effect/guidance/:

File	Contents
effect-first-development.md	The full Effect-first specification: 40+ numbered laws (EF-1 … EF-40) covering tagged errors, Option, schema, canonical imports, Match, services & layers, Clock, observability, Duration, JSON via Schema, scoped resources, retries, timeouts, structured concurrency, parallel concurrency, Config, Redacted, defects vs. failures, layer memoization isolation, schema-first domain modeling, schema defaults, branded guards, equivalence, transformations, native sort, dual APIs. Followed by copy-paste templates and a 45-item LLM review checklist.
post__effect-and-the-near-inexpressible-majesty-of-layers.md	A long-form essay defending Effect's Layer type. Included for the same reason a system prompt cites a style guide: priors matter.
post__parse-dont-validate.md	A long-form essay on type-driven design: push parsing to boundaries, refine data into more precise types, and make illegal states unrepresentable instead of re-checking validated-but-unrefined inputs.
progressive-disclosure-guidance.md	Short, imperative agent rules: "load AT LEAST 5 effect-* skills before any Effect work; if anything is unclear, read from ~/.cache/effect-v4/." It includes the reference clone's generated AI docs, major user-facing guides, cookbook material, and source directory.

Followed by a runtime line:

pi-effect-harness policy:
- Before planning or writing Effect code, read at least 5 relevant effect-* skills.
  Loaded on this branch: 3/5 (effect-error-handling, effect-layer-design, effect-schema-v4).
- If any Effect v4 API is unclear, read from the local Effect reference clone instead of guessing.
- Key reference paths:
  - ~/.cache/effect-v4/LLMS.md — generated task-oriented guide and example index
  - ~/.cache/effect-v4/ai-docs/src/ — source examples behind LLMS.md, organized by topic
  - ~/.cache/effect-v4/packages/effect/SCHEMA.md — Schema reference
  - ~/.cache/effect-v4/packages/effect/HTTPAPI.md — HttpApi, HttpApiClient, and HttpApiBuilder reference
  - ~/.cache/effect-v4/packages/effect/CONFIG.md — Config and ConfigProvider reference
  - ~/.cache/effect-v4/packages/effect/MCP.md — MCP server reference
  - ~/.cache/effect-v4/packages/effect/OPTIC.md — Optic reference
  - ~/.cache/effect-v4/packages/vitest/README.md — @effect/vitest testing reference
  - ~/.cache/effect-v4/cookbooks/schedule.md — Schedule recipes and traps
  - ~/.cache/effect-v4/packages/effect/src/ — source of truth for every exported module

The skill preview is sorted, capped at 5 names, with (+N more) for overflow. The full guidance is loaded once at layer construction and re-emitted from memory each turn.

The pattern feedback loop

After a successful write, every pattern under patterns/ is matched against the actual post-write file via PatternMatcher. Each pattern is a markdown file with YAML frontmatter:

---
action: context
tool: (edit|write)
event: after
name: avoid-data-tagged-error
description: Use Schema.TaggedErrorClass instead of Data.TaggedError for serialization and RPC compatibility
glob: '**/*.{ts,tsx}'
detector: ast
pattern: Data.TaggedError($$$)
level: warning
suggestSkills:
    - effect-error-handling
---

# Use `Schema.TaggedErrorClass` Instead of `Data.TaggedError`
…

Detectors are either ast-grep rules (single pattern, list of patterns, or full rule object with inside / constraints) or regex with comment-skipping. Severity levels are critical, high, medium, warning, info. Matches are de-duplicated, sorted by severity, and emitted as a single Decision.InjectUserMessage:

pi-effect-harness review request:
File: `src/services/MyThing.ts`

I noticed potential Effect-pattern issues in the write you just completed.
Please inspect this change now.
If the warning is valid, revise the code before continuing.
If you believe it is a false positive or an intentional exception, briefly say so and continue.

Matched patterns:
- avoid-data-tagged-error [warning]: Use Schema.TaggedErrorClass instead of Data.TaggedError…

Relevant guidance:
## avoid-data-tagged-error
…(the full body of the pattern's markdown, plus suggested skills hints)…

The pattern bodies use a Haskell-style transformation diagram convention — type signatures for the bad and good forms, then a one-paragraph rationale. This is harness-internal style, not a requirement; you can fork the patterns and use whatever rationale format you prefer.

The suggestedSkills field is appended to the matched-pattern feedback as: "If you have not loaded the effect-error-handling skill, you should load it before continuing." This closes the feedback loop: a pattern miss surfaces both the rule and the skill that documents it.

The reference clone

Effect v4 is moving fast. Beta releases ship with API renames in nearly every minor (catchAll → catch, parseJson → fromJsonString, Either → Result, compose → decodeTo, the entire *FromSelf suffix removal, etc.). The most reliable way to keep an agent honest is to give it the source.

After /toggle-effect-harness is enabled, and again on enabled session starts / before agent turns, EnsureReferenceClone maintains a single user-scoped clone of Effect-TS/effect-smol at ~/.cache/effect-v4/. If the cache is absent, it runs git clone --depth 1 --single-branch into ~/.cache/effect-v4.cloning/ and atomically renames it into place. If the cache already exists, it refreshes origin, updates origin/HEAD, and hard-resets to the latest Effect v4 beta source commit.

Properties:

• Atomic first clone: the initial clone happens in a temp directory and is rename()-d into place. Either ~/.cache/effect-v4/ is present and complete, or it is absent.
• Shared: the cache is user-scoped, not project-scoped; all projects with Effect mode enabled reuse the same clone.
• Always refreshed: existing clones fetch origin with depth 1, update origin/HEAD, reset to it, and clean untracked files. No project-local effect version is detected or matched.
• Single-flight: a module-level clonePromise deduplicates concurrent invocations across hooks, and a lightweight cache lock avoids cross-process clone/update races.
• Fail-silent: a clone or refresh failure (no network, git not on PATH) never blocks the agent. The harness continues without the reference; the policy header still tells the agent the paths to look for.

The agent doesn't have to know any of this. It sees the generated docs, major user-facing guides, cookbook material, and source directory from ~/.cache/effect-v4/ mentioned in the policy header, and reads them like any other file.

---

Skill catalog

41 skills, all loaded into Pi's /skill: namespace.

AI / LLM (6)

Skill	Description
effect-ai-chat	Stateful AI chat sessions with the Effect Chat module — multi-turn conversations, agentic tool-calling loops, persistence, streaming, structured object generation.
effect-ai-language-model	The Effect AI LanguageModel service — text generation, structured output, streaming, tool calling, schema-validated responses.
effect-ai-prompt	The complete Prompt API for constructing, merging, and manipulating LLM conversations using messages, parts, and composition operators.
effect-ai-provider	@effect/ai provider layers (Anthropic, OpenAI, OpenAI-Compat, OpenRouter) with config management, model abstraction, ExecutionPlan fallback, runtime overrides.
effect-ai-streaming	Streaming response patterns: start/delta/end protocol, accumulation strategies, resource-safe consumption, history management with SubscriptionRef.
effect-ai-tool	Tool and Toolkit APIs — type-safe tool definitions, parameter validation, handler implementations, user- and provider-defined tools.

Schema & domain modeling (8)

Skill	Description
effect-schema-v4	Authoritative reference for Effect Schema v4 API changes and v3 → v4 migration. Find-and-replace tables, breaking changes, idiom shifts.
effect-schema-composition	Schema.decodeTo, transformations, filters, multi-stage validation.
effect-domain-modeling	Production-ready domain models with Schema.TaggedStruct — ADTs, predicates, orders, guards, match functions.
effect-domain-predicates	Comprehensive predicates and orders for domain types using typeclass patterns.
effect-typeclass-design	Curried signatures and dual data-first / data-last APIs.
effect-pattern-matching	Data.TaggedEnum, $match, $is, Match.typeTags, Effect.match. Avoid manual _tag checks.
effect-context-witness	When to use Context.Service witness vs. capability patterns; coupling trade-offs.
effect-optics	Iso, Lens, Prism, Optional, Traversal — composable, type-safe access and immutable updates to nested data.

Layers, services, runtime (5)

Skill	Description
effect-layer-design	Designing and composing layers for clean dependency management.
effect-service-implementation	Fine-grained service capabilities; avoiding monolithic designs.
effect-managed-runtime	Bridging Effect into non-Effect frameworks (Hono, Express, Fastify, Lambda, Workers) via ManagedRuntime.
effect-platform-abstraction	Cross-platform file I/O, process spawning, HTTP clients, terminal — the abstraction itself.
effect-platform-layers	Structuring platform-layer provision for cross-platform applications.

Errors, config, observability (4)

Skill	Description
effect-error-handling	Schema.TaggedErrorClass, catchTag/catchTags, catchReason/catchReasons, Cause, ErrorReporter, recovery patterns.
effect-config	Config and ConfigProvider — env vars, structured config, test config, .env, JSON, custom sources.
effect-observability	Structured logging, distributed tracing, metrics; OTLP/Prometheus export.
effect-wide-events	Wide events (canonical log lines) for observability. Conceptual guide for instrumentation strategy.

Data, IO, concurrency (7)

Skill	Description
effect-stream	Pull-based streaming pipelines — creation, transformation, consumption, encoding (NDJSON/Msgpack), concurrency, resource safety.
effect-batching	Request, RequestResolver, SqlResolver — N+1 elimination, batched data-fetching layers, request caching.
effect-pubsub-event-bus	Typed event buses with PubSub and Stream.
effect-filesystem	Cross-platform file I/O across Node.js, Bun, browser.
effect-path	Cross-platform path operations — joining, resolving, URL conversion.
effect-command-executor	ChildProcess — shell commands, captured output, piping, streaming, scoped lifecycle.
effect-concurrency-testing	Testing PubSub, Deferred, Latch, Fiber, SubscriptionRef, Stream.

Persistence & networking (4)

Skill	Description
effect-sql	SqlClient, SqlSchema, SqlModel (CRUD repos), SqlResolver, Migrator.
effect-http-api	HttpApi, HttpApiClient, HttpApiBuilder — typed endpoints, security middleware, OpenAPI, derived clients.
effect-rpc-cluster	RPC endpoints, cluster routing, workflow patterns with Effect RPC and Cluster.
effect-workflow	Durable workflows with Workflow, Activity, DurableClock, DurableDeferred — execution that survives restarts, compensation (saga), distribution via Cluster.

CLI & MCP (2)

Skill	Description
effect-cli	Type-safe CLI applications — argument parsing, options, commands, dependency injection.
effect-mcp-server	MCP servers with McpServer, McpSchema, Tool, Toolkit; stdio and HTTP transports.

Testing & migration (2)

Skill	Description
effect-testing	@effect/vitest and it.effect(...) — services, layers, time-dependent effects, error handling, property-based testing.
effect-incremental-migration	Migrating async/Promise-based modules to Effect services while preserving backward compatibility.

React (3)

Skill	Description
effect-atom-state	Reactive state management with Effect Atom for React applications.
effect-react-composition	Composable React components using Effect Atom; avoiding boolean props; integrating with Effect's reactive state.
effect-react-vm	The VM (View Model) pattern for reactive, testable frontend state management.

---

Pattern catalog

46 patterns run after successful edit/write tool calls when the written path matches the pattern's frontmatter glob. Most target TypeScript/TSX, but some use narrower or negated globs. Detectors are declared per pattern as either ast-grep rules or comment-skipping regex.

avoid-* (20)

Pattern	Level	Description
avoid-any	warning	as any and as unknown type assertions.
avoid-data-tagged-error	warning	Data.TaggedError — use Schema.TaggedErrorClass for serialization and RPC compatibility.
avoid-direct-json	info	JSON.parse / JSON.stringify — use Schema.fromJsonString or Schema.UnknownFromJsonString.
avoid-direct-tag-checks	warning	Direct _tag property checks; use exported refinements/predicates.
avoid-expect-in-if	warning	expect() calls nested inside if blocks in tests.
avoid-mutable-state	info	let bindings inside Effect services; prefer Ref.
avoid-native-fetch	warning	Native fetch — use Effect HTTP modules.
avoid-node-imports	warning	Catch-all for node: imports not covered by a dedicated use-*-service rule.
avoid-non-null-assertion	warning	! non-null assertion operator.
avoid-object-type	warning	Object and {} as types.
avoid-option-getorthrow	warning	Option.getOrThrow — use Option.match or Option.getOrElse.
avoid-platform-coupling	warning	Binding packages importing platform-specific packages like @effect/platform-bun.
avoid-process-env	warning	process.env — use Config.*.
avoid-react-hooks	high	useState/useEffect/useReducer etc. — use VMs with Effect Atom.
avoid-schema-suffix	info	Schema constants suffixed with Schema; name them after the domain type.
avoid-sync-fs	high	Synchronous filesystem operations.
avoid-try-catch	warning	try/catch in Effect code — use Effect.try or typed errors.
avoid-ts-ignore	warning	@ts-ignore and @ts-expect-error.
avoid-untagged-errors	warning	new Error(...) and instanceof Error for recoverable failures — use Schema.TaggedErrorClass.
avoid-yield-ref	warning	Direct yield* Ref/Deferred/Fiber/Latch (removed in v4); use explicit method calls.

prefer-* (7)

Pattern	Level	Description
prefer-arr-sort	warning	Arr.sort with explicit Order over native Array.prototype.sort.
prefer-duration-values	warning	Duration helpers over numeric literals for time.
prefer-effect-fn	warning	Effect.fn for service methods (automatic tracing) over plain Effect.gen wrappers.
prefer-match-over-switch	warning	Match over native switch.
prefer-option-over-null	info	Option over T | null unions.
prefer-redacted-config	warning	Config.redacted / Schema.Redacted for secrets.
prefer-schema-class	warning	Schema.Class over Schema.Struct for object/domain schemas.

use-* (8)

Pattern	Level	Description
use-clock-service	warning	Clock / DateTime over new Date(...) and Date.* statics.
use-command-executor-service	warning	ChildProcessSpawner / CommandExecutor over node:child_process.
use-console-service	warning	Console / Effect.log* over console.*.
use-filesystem-service	high	FileSystem service over direct node:fs / node:fs/promises imports.
use-http-client-service	warning	Effect HttpClient over node:http / node:https.
use-path-service	warning	Path service over direct node:path imports.
use-random-service	warning	Random service over Math.random().
use-temp-file-scoped	warning	makeTempFileScoped / makeTempDirectoryScoped over os.tmpdir() or non-scoped variants.

Other (11)

Pattern	Level	Description
casting-awareness	info	Type assertions in general — use type-safe alternatives.
context-tag-extends	warning	Context.Tag, Effect.Service, and legacy ServiceMap.* APIs — use Context.Service.
effect-catchall-default	warning	Broad Effect.catch defaults in domain logic — use catchTag unless it's an explicit boundary fallback.
effect-promise-vs-trypromise	warning	Effect.promise over Effect.tryPromise (loses error handling).
effect-run-in-body	warning	Effect.runSync / runPromise outside entry points.
imperative-loops	warning	for / for...of / while / do...while loops — use functional transformations or Effect.forEach.
require-effect-concurrency	warning	Effect.forEach / all / validate without explicit concurrency on non-trivial fan-out.
stream-large-files	info	Whole-file reads when the path looks large or unbounded.
throw-in-effect-gen	critical	throw inside Effect.gen — use yield* Effect.fail().
vm-in-wrong-file	critical	View Model definitions outside .vm.ts files.
yield-in-for-loop	warning	yield* in for loops — use Effect.forEach / STM.forEach.

Each pattern's full markdown body — usually a Haskell-style transformation diagram, rationale, and a hint to load specific effect-* skills — is what gets sent back to the agent on a match.

---

Configuration

Reference clone location and refresh

The reference clone is hardcoded to ~/.cache/effect-v4/ (path.join(os.homedir(), '.cache', 'effect-v4')). It is shared across every project on the machine. The harness does not read node_modules/effect/package.json, does not compute an effect@<version> tag, and does not create project-local reference directories.

When Effect mode is enabled, session-start and before-turn hooks ensure the cache exists and refresh existing clones to the latest Effect v4 beta source in Effect-TS/effect-smol.

Skill threshold

MIN_EFFECT_SKILLS = 5, defined in harnesses/effect/src/constants.ts. Not currently configurable per-project; if you want a different threshold, fork.

Effect-code regex

\bEffect\b|from\s+['"]effect(?:\/[^'"]*)?['"]

Matches an Effect identifier or any from "effect..." import. The gate is intentionally permissive — false positives on the gate are safe (the agent reads more skills); false negatives are not.

What this extension never does

• Modifies application source files directly. It may create/update ~/.cache/effect-v4/ for the shared reference clone and Pi's project-scoped session-state file for mode persistence.
• Blocks Read tool calls. The gate fires on writes only.
• Persists state across projects. Mode state is project-scoped.
• Calls the network outside git clone / git fetch for the reference repo.
• Talks to Pi events outside the lifecycle listed above.

---

Caveats

• Beta on beta. Effect v4 is itself in beta, and so is this harness. Keep your project dependency current deliberately. The reference clone tracks the latest Effect v4 beta source rather than any project-local dependency version, so still trust typecheck/tests for ABI compatibility.
• The patterns are tripwires, not a linter. They catch the common v3 → v4 confusions and the most expensive-to-debug Effect-specific mistakes. They do not replace bun run check && bun run test. Treat a clean pattern run as "the agent didn't trigger the obvious traps," not as "the code is correct."
• The skill gate is branch-scoped, not session-scoped. /compact, /fork, and /clone reset the loaded-skill set. This is deliberate: post-compaction, the agent has a smaller working memory, and re-establishing the relevant skill context is cheaper than letting it write Effect code from a partial summary.
• First cache creation and refresh require git on PATH and network access. If clone/refresh fails, the harness continues without blocking the agent. The policy header still points at the cache path; re-toggling /toggle-effect-harness or starting the next turn retries.
• The pattern-feedback loop runs after every successful write. On a large refactor the agent may receive several pattern-feedback messages in a row. This is by design — each one is severity-sorted and de-duplicated, but the rate is determined by the rate of writes.

---

Development

bun install
bun run check    # dprint format + oxlint + tsgo typecheck
bun run test     # vitest run (all tests)

See AGENTS.md and CONTRIBUTING.md for project structure, code style, and PR guidelines.

The harness is built on a small internal kernel (packages/harness-kit) that wraps Pi's ExtensionAPI in Effect — Decision, HarnessRule, HookSet, RuleEngine, WriteProjection, PatternCatalog, PatternMatcher. The kernel may eventually be lifted out as a standalone library for building other Pi harnesses; for now treat the Effect harness as the product and the kernel as an implementation detail.

---

License

MIT © Marc Suesser

---

• Pi — the coding agent this extension plugs into.
• Effect — what this extension is opinionated about.
• Effect-TS/effect-smol — the source the reference clone tracks.
• Kit Langton (@kitlangton) — primary source for the "near-inexpressible majesty of layers" guidance essay.
• Alexis King, "Parse, don’t validate" — source for the post__parse-dont-validate.md guidance essay.
• kriegcloud/beep-effect — the earliest version of the effect-first-development guidance doc was sourced from here.