Archetype is an AI-native repository. Humans are absolutely welcome to contribute, but the preferred workflow is to turn proposed work into a clear issue and then have an agent implement it in a branch with a PR.

That keeps the work explicit, reviewable, and grounded in the contracts this repo is trying to preserve.

Recommended Workflow¶

If you want to contribute, the recommended path is:

1. Open an issue that describes the work as a prompt.
2. Include scope, acceptance criteria, and any contract constraints.
3. Have an agent work the issue in a dedicated workspace or branch.
4. Review the resulting PR as you would review any other engineering change.

For simple typo fixes or small docs changes, you can still contribute directly. For runtime, service-layer, or engine behavior changes, issue-first is the recommended default.

Read These First¶

These documents are the current orientation pack for contributors:

If you skip one document, do not skip LEARNINGS.md.

Contribution Policy¶

This repository is opinionated about where changes should land.

If you are proposing a core behavior change, you should document the contract first and only then change the implementation.

Contracts We Enforce¶

Contributors are expected to preserve, and when needed document, the contracts that now govern this codebase.

Engine and app contracts¶

See Specification.

These cover:

• component and archetype identity
• append-only store behavior
• querier, updater, and processor ordering semantics
• world execution and mutation materialization
• brokered command flow
• multi-world runtime isolation
• idempotent versus non-idempotent boundaries

Sugar and runtime contracts¶

See Specification, especially the top-level runtime and sugar contracts section.

These cover:

• pure wrapper construction
• single-flight lazy activation
• honest spawn() return semantics
• runtime-vs-world lifetime boundaries
• explicit script ceremony
• public export stability
• governance-preserving ergonomics

Executable contract suites¶

Some of the most important contracts are enforced directly in tests:

• tests/app/test_sugar_runtime.py
• tests/sync/test_sync_stack_contracts.py
• tests/integration/test_command_flow.py
• tests/app/test_services.py
• tests/cli/test_cli.py

If you change behavior, update or add the contract test that proves the new behavior is intentional.

Issue Template Guidance¶

The best issues are written as implementation prompts.

A good issue should include:

• the user-facing or system-facing problem
• the affected layer for example core, app, api, cli, docs, or examples
• whether this is a bug fix, contract clarification, feature, or refactor
• acceptance criteria
• any relevant specification or requirements references
• test expectations

Good examples:

• "Make SimulationService.run() preserve one logical run_id across the full run and add regression coverage."
• "Document the world-local shutdown contract for the sugar runtime and add smoke tests."
• "Fix QueryService so it either implements real reads or is clearly documented as provisional."

Development Workflow¶

Setup¶

git clone https://github.com/VangelisTech/archetype.git
cd archetype
uv sync --group dev

Useful commands¶

make test        # fast test suite
make test-cov    # test suite with coverage report
make check       # format + lint
make ci          # main gate: lint + lock-check + tests with coverage
uv run mkdocs build

Before you open a PR¶

At minimum:

• run make test
• run make check or the relevant lint/format commands
• run uv run mkdocs build if you touched docs

For broad changes, prefer make ci.

How to Structure Changes¶

Keep the work narrow and contract-driven.

• Start with the behavioral contract, not the implementation detail.
• Add or update a regression test before or alongside the fix.
• Prefer service-layer changes over core changes when both could solve the same problem.
• Do not bypass the broker, runtime, or world lifecycle semantics just to make a wrapper API feel shorter.
• If a proposed ergonomic change weakens a contract, document the tradeoff and get agreement before implementing it.

Pull Requests¶

PRs should explain:

• what changed
• why the change is needed
• what contract it preserves, introduces, or modifies
• how it was validated

If behavior changed, include the test that proves it.

If the change touches docs, examples, and code, keep them aligned in the same PR whenever practical.

What Reviewers Will Look For¶

Review in this repository is not just "does it work."

Reviewers should ask:

• Does this preserve the existing contract?
• If it changes the contract, is that documented explicitly?
• Is the right layer changing?
• Are the tests proving behavior or just making the suite green?
• Does this align with LEARNINGS.md and the spec documents?

When to Avoid a PR¶

Do not send an implementation PR first when the real question is architectural.

Open an issue first if:

• the change would alter command semantics
• the change crosses runtime or world lifetime boundaries
• the change affects multi-world behavior
• the change touches src/archetype/core/
• the change conflicts with a documented contract

That discussion should happen before code lands.