Clarify project guidance and release workflows

Author: SandroMaglione

.agents/skills/effect-machine-pr/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: effect-machine-pr
+description: Run the complete Effect Machine implementation-to-merge workflow. Use only when the user explicitly invokes `$effect-machine-pr` and wants a repository change implemented from the latest base branch through local validation, a pull request, CI and performance checks, and merge. Do not use for design, review, diagnosis, or implementation that should stop before publication.
+---
+
+# Effect Machine PR
+
+Ship the requested change through a green, merged pull request. Treat invocation as authorization for the in-scope branch, commits, push, pull request, CI fixes, and final merge; it does not authorize unrelated changes, bypassing protections, or destructive recovery.
+
+## Establish the baseline
+
+1. Read `AGENTS.md` and every instruction it routes to before changing files.
+2. Inspect the worktree and preserve all user-owned changes. Never discard or overwrite unrelated work.
+3. Use the base branch named by the user, or `main` by default.
+4. Fetch the latest remote base. In its primary worktree, switch to the base and run a fast-forward-only pull. If the base is checked out in another worktree, branch directly from the freshly fetched `origin/<base>` commit instead.
+5. Create a focused `codex/` branch unless the user specifies another name.
+
+## Implement the complete change
+
+1. Inspect the relevant public API, internals, tests, documentation, examples, and analogous Effect implementation before editing.
+2. Implement the long-term design, including generic and optimized semantics where applicable. Follow the Cluster ownership boundary in `AGENTS.md`.
+3. Add observable runtime tests, typetests, differential tests, JSDocs, README or guide updates, and example changes required to make the feature complete.
+4. Add a changeset when required. Use minor for a public addition or breaking change and patch for a compatible fix or implementation improvement. Never use major before 1.0.
+5. Keep the changeset user-facing: explain the resulting API and direct migration, not implementation history or external inspiration.
+
+## Validate locally
+
+1. Run `pnpm check`.
+2. Run `pnpm check` in every affected package directly below `examples/`.
+3. Run `pnpm perf:types` for changes that affect the public TypeScript API or inference.
+4. Always run `pnpm perf:runtime` before publishing this full-lifecycle workflow. Treat the local run as a functional smoke test; the CI base-versus-PR comparison is authoritative.
+5. Fix every failure and repeat all affected checks. Treat correctness, type safety, runtime performance, and memory regressions as blockers.
+6. Audit the final diff, formatting, generated files, public terminology, changeset level, and working-tree scope.
+
+## Publish and merge
+
+1. Stage only the intended files, commit with a concise outcome-oriented message, and confirm the worktree is clean.
+2. Fetch the remote base again before pushing. If it advanced materially, integrate it safely and repeat affected validation.
+3. Push the branch and open a ready pull request using the repository template. Record the changeset decision and validation without copying noisy local benchmark tables.
+4. Monitor every required check, example job, and type/runtime performance workflow. Inspect the base-versus-PR reports, not only the aggregate green status.
+5. Diagnose failures from their logs, implement in-scope fixes, rerun relevant local checks, push, and continue monitoring. Never weaken semantics, inference, tests, or thresholds to make CI pass.
+6. Merge only when the pull request is current, mergeable, and every required check is green. Use the repository's normal squash-and-branch-cleanup convention unless instructed otherwise.
+7. Verify the pull request's remote state even if the merge command reports a local worktree checkout error. Confirm the merge commit is present on `origin/<base>` and the remote feature branch was removed.
+
+Keep the user informed during long checks. Do not stop at an open pull request or merely enable auto-merge. If repository protection, an approval, credentials, or an external outage prevents completion, exhaust safe checks and report the precise blocker.

.agents/skills/effect-machine-pr/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Effect Machine PR"
+  short_description: "Implement, validate, and merge an Effect Machine PR"
+  default_prompt: "Use $effect-machine-pr to implement this change through a green, merged pull request."
+policy:
+  allow_implicit_invocation: false

.agents/skills/effect-machine-release/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: effect-machine-release
+description: Run the complete Effect Machine implementation and release workflow. Use only when the user explicitly invokes `$effect-machine-release` and wants a change implemented, validated, merged, included in the Changesets version pull request, and published by the release workflow. Do not use when the requested endpoint is only a feature pull request or merge to main.
+---
+
+# Effect Machine Release
+
+Ship the requested change through its feature pull request, the bot-owned Changesets version pull request, and the resulting publish workflow. Treat invocation as authorization to merge both validated pull requests; it does not authorize bypassing protections or merging unrelated, unverified work.
+
+## Ship the feature pull request
+
+Before acting, read `../effect-machine-pr/SKILL.md` completely and follow its entire implementation-to-merge workflow. Review the changeset before merging the feature pull request so its level and published text will not need repair later.
+
+## Find the release pull request
+
+1. After the feature merge, inspect the current `.github/workflows/release.yml`; follow the repository's actual Changesets and publish workflow rather than assuming it is unchanged.
+2. Fetch `main` and wait for the Changesets action to create or update its pull request. Identify it by the expected base, bot author, and `changeset-release/main` head branch, not by title alone.
+3. Confirm the release pull request's head includes the feature merge. Continue waiting if an older run or head revision does not yet contain it.
+4. Inspect the complete diff. Verify the consumed changeset appears in the generated package version and changelog, the migration text remains accurate, and no major version is introduced before 1.0.
+5. Aggregated release entries are allowed only when they correspond to changesets already merged into the base. Do not merge arbitrary code changes or an untrusted lookalike pull request.
+
+## Validate and merge the release
+
+1. Monitor every required check on the current release head. If the bot updates the branch, restart the review and wait for checks on the new head.
+2. Treat versioning, changelog, packaging, correctness, and performance failures as blockers. Do not edit generated release output merely to bypass the source of a failure.
+3. Merge the release pull request only when its identity and contents are verified, it is current and mergeable, and all required checks are green.
+4. Verify the release merge commit on `origin/main` and confirm the release pull request is closed as merged.
+
+## Verify publication
+
+1. Monitor the release workflow triggered by the release merge. Distinguish the Changesets/version pull request from actual package publication.
+2. Confirm the Changesets action reports publication, the expected package version and tag exist, and any triggered website deployment succeeds.
+3. Report the feature pull request, release pull request, merge commits, released version, and publication status.
+
+Keep waiting through normal bot and CI latency and provide concise progress updates. Do not stop merely because the release pull request has not appeared yet. If environment approval, credentials, repository protection, malformed aggregated content, or an external outage requires new authority, report the exact blocker without weakening the workflow.

.agents/skills/effect-machine-release/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Effect Machine Release"
+  short_description: "Ship through the Changesets release PR"
+  default_prompt: "Use $effect-machine-release to implement this change, merge its pull request, and complete the Changesets release."
+policy:
+  allow_implicit_invocation: false

.changeset/README.md

@@ -2,6 +2,15 @@
 
 Run `pnpm changeset` for every user-facing change.
 
+## Pre-1.0 versioning
+
+Effect Machine is experimental and pre-1.0. Use only:
+
+- `minor` for a public addition or breaking API change;
+- `patch` for a compatible fix or implementation improvement that requires a changeset.
+
+Do not create a major changeset before 1.0. Backward compatibility is not a design goal during this phase: prefer the clearest long-term API and provide a direct migration instead of adding deprecated aliases or compatibility wrappers.
+
 ## Writing changelog entries
 
 Changeset descriptions are published directly on the documentation website. Write them for library users rather than repository maintainers.
@@ -12,6 +21,7 @@ Changeset descriptions are published directly on the documentation website. Writ
 - Use inline code for API names, types, and short expressions.
 - Include at most one small fenced TypeScript example when an API is added or its usage changes meaningfully.
 - For a breaking change, state what changed and show the replacement or migration directly.
+- Describe the resulting API rather than the external library that inspired it.
 - Omit commit hashes, pull request numbers, implementation history, test details, and internal refactoring unless they affect users.
 
 A typical API entry looks like:

AGENTS.md

@@ -1,10 +1,32 @@
 # Project guidance
 
-A core objective of the library is type safety and ease of use of the user-facing API, for both humans and agents.
+Effect Machine is intended to become part of the core `effect` library. Treat that as an architectural requirement: public APIs, failures, module boundaries, ownership, and implementation patterns must meet Effect's standards and fit its general API shape.
 
-The goal is eventually to merge this inside the core of the `effect` library, so plan changes according to the patterns and expectations of `effect`.
+## Product priorities
 
-Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.
+Apply these priorities in order:
+
+1. **Type safety.** Make invalid states, events, compositions, references, and capabilities unrepresentable at compile time whenever possible. Preserve typed Effect failures at runtime; validation must not escape as an accidental throw.
+2. **Explicit, opinionated semantics.** Similar concepts need distinct names and contracts. Do not hide a material semantic choice behind an omission, permissive overload, or ambiguous default. Convenience should come from builders and inference, not weaker boundaries.
+3. **Readable, concise models.** A human should be able to read a machine definition from top to bottom and understand its protocols, topology, behavior, and effects. Prefer declarative builders and eliminate raw schema plumbing, duplicated declarations, and incidental ceremony. Concision must not obscure intent.
+4. **Effect-core alignment.** Follow Effect naming, failure, `Scope`, `Stream`, service, module, and ownership conventions. Inspect analogous implementations under `references/effect` before designing a new abstraction.
+
+When compatibility, convenience, concision, and semantic clarity conflict, prefer type safety and semantic clarity. Then optimize the resulting API for readable models. Make architectural decisions for the long term; do not accept a stopgap intended to be replaced later.
+
+## Experimental versioning
+
+- The library is experimental and pre-1.0. Public additions and breaking API changes use a minor changeset; compatible fixes and implementation improvements use a patch changeset. Do not create major changesets before 1.0.
+- Backward compatibility is not currently a design goal. Change or remove an existing API whenever a clearer, safer, smaller long-term design replaces it.
+- Do not add deprecated aliases, compatibility wrappers, or parallel APIs solely to preserve an inferior existing design unless the user explicitly requests them.
+- Explain the resulting API and direct migration in changesets. Do not use changelog entries to credit an external library or narrate implementation history.
+
+## Effect and Cluster boundaries
+
+- Effect Machine owns declarative state modelling, typed machine protocols, local machine references, child lifecycles, execution, and observation.
+- Effect Cluster owns distributed identity, placement, discovery, transport, routing, delivery, sharding, and remote lifecycle semantics. Do not recreate those capabilities in the core machine API.
+- Before exporting a new name or capability, inspect Effect's public modules and the relevant implementation under `references/effect`, with explicit attention to Cluster. Avoid names that already carry a different Cluster meaning, especially actor-, entity-, shard-, node-, and distributed-reference terminology.
+- Reuse Cluster terminology only when the semantics genuinely match and the integration is intentional and documented. Do not introduce a local lookalike with a different contract.
+- Keep necessary Cluster integration behind an explicit adapter or integration module. Do not leak distributed concerns into the local machine model.
 
 ## Effect internal standards
 

README.md

@@ -10,6 +10,27 @@ cluster adapter.
 > This is early-release software. Its API may change, and each release targets
 > one exact Effect beta.
 
+## Design principles
+
+- **Type-safe by construction:** reject invalid protocols, compositions, and
+  capabilities at compile time where possible, and preserve typed Effect
+  failures at runtime.
+- **Explicit and opinionated:** give different semantics different names and
+  contracts. Builders and inference remove ceremony without making behavior
+  depend on ambiguous omissions.
+- **Readable models:** keep schemas, topology, behavior, and effects concise
+  enough that a human can understand the complete model from its definition.
+- **Effect-native:** design toward eventual inclusion in Effect core and follow
+  its API shape, module boundaries, ownership, and failure conventions.
+
+The package is pre-1.0: a clearer or safer long-term API takes priority over
+backward compatibility. Breaking changes use minor releases, compatible fixes
+use patch releases, and compatibility aliases are not added by default.
+
+The core machine model remains local. Distributed identity, placement,
+transport, routing, delivery, and remote lifecycle semantics belong to Effect
+Cluster and are exposed only through explicit integration boundaries.
+
 ## Install
 
 ```sh

docs/agent-guide.md

@@ -4,6 +4,21 @@ This is the model-facing reference for the currently published
 `@typeonce/effect-machine` API. Prefer these patterns over reconstructing the API
 from its internal implementation.
 
+## Design priorities
+
+Prefer, in order: compile-time type safety, explicit and opinionated semantics,
+readable and concise machine models, and alignment with Effect core. Convenience
+must come from builders and inference rather than ambiguous omissions or weaker
+contracts. The package is pre-1.0, so improve or remove an existing API when a
+clearer long-term design replaces it; do not preserve an inferior design with
+aliases by default.
+
+Keep the core machine model local. Before adding a public name or capability,
+check Effect's existing modules and especially Cluster. Distributed identity,
+placement, discovery, transport, routing, delivery, sharding, and remote
+lifecycle belong to Cluster; expose integration through an explicit adapter
+instead of creating a similar local abstraction with different semantics.
+
 ## Public imports
 
 ```ts