Jixu AGENTS.md

Jixu Repository Instructions

These instructions apply to every human or AI agent changing this repository.

1. Read order

Before proposing or making a change, read:

1. SPEC.md — normative product behavior and architecture;
2. this file — repository working rules;
3. the relevant implementation and tests; and
4. any directly relevant ADR or package documentation.

Do not infer architecture from filenames, examples, or provider SDKs when the specification already defines it.

2. Sources of truth

• The ordered durable Event log is the sole authority for a Thread.
• State is derived from Events.
• A Checkpoint is a disposable performance cache.
• A Signal is transient and non-authoritative.
• Provider conversation state, UI state, traces, and in-memory objects are not runtime authority.
• SPEC.md is the authority for public semantics and package boundaries at the current commit. It is a living specification, not an immutable artifact.

Never introduce a second Thread state machine, a second Event history, or a second component that can independently decide canonical Thread status.

3. Canonical concepts

Use the terminology in SPEC.md exactly:

• Harness owns exactly one immutable Agent and binds Stores and Drivers to the Kernel, but is not durable authority.
• Agent is immutable configuration and never hands work to another Agent.
• Thread is one durable, multi-turn history for that Agent.
• Kernel is I/O-free domain logic.
• Event is an immutable durable fact.
• Signal is a transient observation.
• State is the deterministic Event projection.
• Reducer is pure.
• Effect requests external work.
• Driver performs an Effect.
• Tool acts.
• Skill supplies instructional context.
• Checkpoint accelerates recovery but is not authority.
• Fork creates a new Thread.
• Replay performs no Effects.

Do not introduce session, conversation, run, workflow, job, or task as a synonym or wrapper for Thread. Multi-Agent orchestration, handoff, supervisors, swarms, Agent graphs, and Agent-as-Tool are outside the Jixu core model. If an application needs a different Agent, it creates a different Harness rather than adding Agent routing to one Harness.