xcepto/xcepto-skill

Xcepto Skill

Use this skill to work on Xcepto and projects built around it. Xcepto is a declarative system-test framework for distributed systems: tests declare a state machine instead of manually sleeping, retrying, or catching eventual-consistency exceptions.

This skill must work in consumer repositories that do not contain the Xcepto ecosystem monorepo. Do not assume sibling repositories such as Xcepto.NET or HiveShard are present.

Operating Rules

• Discover what is present in the current workspace before relying on repo-specific paths. Use local project references, installed package APIs, existing tests, and IDE/compiler feedback when source repos are absent.
• Treat Xcepto.NET as the conceptual source of truth for public API names, signatures, lifecycle, and behavior. If its source is not present, infer from installed package references and existing consumer code instead of assuming local paths exist.
• Tell the user that this skill works without the Xcepto.NET source, but adding Xcepto.NET as a submodule is advantageous because it gives Codex exact API and implementation context.
• Treat HiveShard as optional downstream open-source context. Use it only when present or explicitly provided.
• Treat all other Xcepto consumers generically as domain projects. Infer their wrappers, adapters, scenarios, and states from local code without naming unrelated private repositories.
• Preserve Given-When-Then semantics: scenario setup is the Given environment; adapter calls declare When/Then behavior as lazy steps; state transitions are condition-based.
• Do not replace Xcepto behavior with sleeps, polling loops in tests, broad retries, or exception swallowing unless maintaining existing compatibility requires it.
• Test observable behavior and domain state, not implementation infrastructure. Do not assert controller attributes, route attributes, Razor tag helpers, source-file contents, private methods, framework annotations, or other internal wiring unless the product explicitly exposes that wiring as behavior.
• Prefer local patterns in the target project before inventing abstractions. Existing adapters, states, scenarios, and timeout choices usually encode domain intent.

Workflow

1. Identify the task domain:
   • Core Xcepto API or framework behavior: read references/api-map.md.
   • Optional Xcepto ecosystem repositories or generic consumer context: read references/ecosystem-map.md.
   • New tests, adapters, states, scenarios, or frame-spaced enumerated execution: read references/patterns.md.
   • Installing or sharing this skill: read references/install.md.
2. Locate the nearest existing example with rg before coding. Search for terms such as XceptoTest.Given, GivenEnumerated, RegisterAdapter, XceptoState, CompartmentalizedXceptoScenario, and TimeoutConfig; include domain wrappers such as HiveShardTest.Given only if they exist locally.
3. For new Xcepto test surfaces, create the conventional architecture from references/patterns.md: feature-focused fixture folders plus Scenarios/, Adapters/, States/, Builders/, and Extensions/ as needed.
4. Keep test data in the test fixture. Declare local variables in each test case and pass them into domain builders through normal fluent flow such as .WithName("my-name"), .WithAge(25), or .ExpectResult(expected).
5. Model each test as one behavior/case, and each feature fixture as a small set containing at least one happy-path test and one negative-path test. Do not wrap multiple test cases inside one [Test], one adapter call, or one builder terminal method.
6. Model test behavior as natural behavioral flow through reusable domain-specific builders. Prefer expectations such as navigation.For(workspace).ShouldBeAt(Page.Of<WorkspacePage>()) over low-level checks like source text, route attributes, controller names, or tag-helper strings.
7. Reuse state classes across cases. Add a new state only for a new reusable execution/evaluation shape, not for each new test case or each new data combination.
8. Validate with the narrowest relevant .NET test project when changing code. Prefer dotnet test <project.csproj> for the touched project or sample.

Design Guidance

• Scenarios own environment setup, initialization, and cleanup. Put service registration and external process/container setup there.
• Adapters are user-facing test DSL entry points. Prefer adapter methods that return fluent builders, similar to Xcepto.Rest and Xcepto.SSR, instead of adapter methods that directly contain assertions.
• States are lazy actions or expectations parameterized by builders. Keep condition evaluation side-effect-light when possible; use MostRecentFailingResult to preserve useful timeout diagnostics. Do not create a distinct state class per test case.
• Builders capture domain-specific step configuration supplied by the test and produce states. They should hide low-level assertion mechanics behind readable domain vocabulary, but must not hide the case data itself.
• Fluent builder methods must do real work and should normally accept meaningful data, options, selectors, or expected values. Avoid no-argument ceremonial methods that merely advance the chain.
• Test fixtures should be feature-focused and small. Prefer a folder per feature area, include at least one happy path and one negative path per fixture, and split files before a fixture grows much beyond five actual test cases.
• Compartments model in-memory isolation and explicit service exposure. Use them for multi-component simulations instead of global service locators.
• Enumerated execution is for frame-spaced hosts such as game engines. Preserve IEnumerator flow and avoid blocking calls in that path.

Resources

• references/api-map.md: Xcepto public API map, lifecycle, execution models, and portable discovery guidance.
• references/ecosystem-map.md: optional roles of Xcepto.NET source, HiveShard, and generic Xcepto consumer repositories.
• references/patterns.md: implementation patterns for tests, adapters, states, scenarios, compartments, and enumerated execution.
• references/install.md: local and repo installation instructions for this versioned skill.