canwu

Imported from PeiyuanQi/canwu (AGENTS.md). Install upstream with npx skills add PeiyuanQi/canwu. Copyright stays with the author.

Agent Instructions

Compatibility

• CLAUDE.md is the Claude Code bridge to this instruction file.

Project Context

• Canwu is a headless historical simulation engine. Rendering, production UI, audio, and animation belong in external clients.
• docs/architecture.md and docs/end-state.md are the architectural source of truth. Keep them aligned with public APIs and dependency boundaries.
• docs/terminology.md is the source of truth for public Canwu terminology. Before writing or translating English or Chinese prose, consult its paired English and 中文规范写法 columns and use those exact terms; do not invent synonyms or translate code identifiers. Keep the repository term sheet and both website terminology pages (website/src/content/docs/en/reference/terminology.mdx and website/src/content/docs/reference/terminology.mdx) synchronized when a public term is added or renamed.
• Follow docs/versioning.md. The root [workspace.package].version is the canonical SemVer version and all first-party crates version in lockstep.
• External mutations must enter through validated commands or canonical ingress. Do not expose a mutable reference to live simulation state.
• Agent-facing reads must be actor-relative and must not leak ground truth.
• Preserve Windows, macOS, and Linux support. Avoid assumptions about path separators, shells, case sensitivity, line endings, or platform-only APIs.

Agent Development Flow

1. Read this file and every nearer AGENTS.md before editing.
2. Inspect git status and preserve user-owned or concurrent changes. Use a worktree for unrelated work; stay in the current checkout when the task explicitly depends on its uncommitted state.
3. Name the invariant being changed and use the change-surface map below to inspect every affected public, persistence, replay, documentation, and test surface before implementation.
4. Make the smallest coherent change. Keep behavior changes separate from large file moves, generated-file refreshes, licensing work, and unrelated cleanup.
5. Treat tests as durable evidence rather than a development process. Admit a committed test only when it is necessary, reusable, non-trivial, and very likely to catch a plausible future regression. Run narrower one-off checks inline without committing them, then run the scoped checks and full repository verification listed below.
6. For public API, persistence, replay, migration, authority, determinism, or performance changes, obtain an independent review before committing. Resolve every blocking finding and re-run the affected checks.
7. Before deploying website, have a separate sub-agent review all website copy in every supported language for fair, good, human-friendly readability. Resolve every blocking finding and re-run the site checks before deployment.
8. Keep implementation and verification uncommitted until the requested change set is complete. When explicitly asked to commit or push, follow the commit economy rules below, stage explicit paths only, use a conventional commit, push without force, and report remaining uncommitted work separately.

Repository hierarchy

• crates/foundation/canwu-core: stable IDs, deterministic RNG, and schema metadata shared across packages.
• crates/foundation/canwu-time: deterministic simulation time and duration arithmetic.
• crates/model/canwu-event: causal event types and evidence references.
• crates/integrations/canwu-reference-world: replaceable example world, detached projection, movement plugin, and routing adapter built on canwu-api.
• crates/model/canwu-knowledge: actor-relative knowledge and observation state.
• crates/model/canwu-decision: persisted decision contracts, controller bindings, utility evaluation, traces, and policy SDK adapters.
• crates/runtime/canwu-sim: authoritative state, ingress, settlement, scheduling, plugins, records, persistence, validation, hashing, migration, and replay.
• crates/api/canwu-api: the supported public API and re-export boundary.
• crates/tools/canwu-debug: reference client; it may depend on canwu-api and first-party reference integrations, never runtime internals.
• docs: canonical architecture, end-state, versioning, conformance, community, and legal documentation.
• website/src/content/docs: published Astro documentation maintained as a separate mirror; public doc changes must update the canonical docs page and its matching Chinese/English website pages, then pass the website build.
• tools/licenses: cargo-about configuration and template inputs for the generated third-party notice bundle.
• benchmarks: deterministic non-CI performance harnesses and recorded baselines; measurement tooling, not authoritative runtime code.
• agent-interface: packaged skills for external Canwu users. canwu-engine covers documentation and public API usage; canwu-developer helps downstream developers build games and historical simulations. Follow its nested AGENTS.md; these are user tools, not runtime simulation plugins.
• .agents/skills: canonical repo-local skills for contributors changing Canwu itself. .claude/skills contains thin Claude-compatible loaders; contributor loaders point here, while downstream-user loaders point to their canonical packaged skills under agent-interface.
• website and assets: community site and project media, outside the authoritative simulation runtime.
• .github: CI workflows, the pull-request template, and repository automation.

Change-surface map

If a change crosses several rows, treat that as one architectural milestone and verify the whole dependency path. Keep application-specific rules and entity types outside Canwu core; downstream packages depend on Canwu's generic public contracts, never the reverse.

Git Workflow

• Prefer git worktrees for parallel or unrelated agent work so multiple agents can develop concurrently without colliding. .worktrees/ is ignored.
• Treat existing uncommitted changes as user-owned unless told otherwise.
• Minimize commit count. Do not create a commit per agent, turn, phase, file, test pass, or review iteration, and do not use checkpoint, progress, WIP, test-fix, or review-fix commits as agent state.
• Unless the user requests a different boundary, keep a normal task uncommitted through implementation and verification. When a commit is requested, produce one coherent final commit for the requested change set.
• If the same task already has an unpublished agent-owned commit, amend it instead of appending another commit. If temporary local fixups already exist, squash them before handoff. Never rewrite commits that predate the task, are user-owned, or have been pushed or shared unless explicitly authorized.
• Use multiple commits only when parts genuinely require independent review, rollback, or release. In multi-agent work, the integrating agent owns the final commit; delegated workers leave changes uncommitted unless assigned an explicit commit boundary.
• Prefer rebase-based conflict resolution unless a task requires a merge.

Coding Rules

• Keep deterministic state in ordered collections and give scheduled work an explicit sequence number.
• Favor typed IDs and references over ownership trees.
• Keep period-specific mechanics in plugins or systems; the core model stays generic.
• Use integer or fixed-unit simulation values where floating-point behavior could affect determinism.
• The debug client depends on canwu-api and canwu-reference-world, not on simulation internals.
• Tests are evidence, not process. The project uses no test-driven-development requirement, test quota, or coverage target.
• Admit a committed test only when it is necessary for a durable contract, reusable across implementations, very likely to fail under a plausible future change, and non-trivial. Non-trivial tests exercise a multi-step invariant, public contract, persistence/replay boundary, or failure recovery path that format, lint, compile, or a simple accessor assertion cannot prove.
• Run useful verification that falls below that bar once inline and leave it out of the committed test suite.

Verification

• Format: cargo fmt --all -- --check
• Lint: cargo clippy --workspace --all-targets -- -D warnings
• Test: cargo test --workspace
• Build debug client: cargo check -p canwu-debug
• Cross-platform CI: .github/workflows/ci.yml runs on Windows, macOS, and Linux.
• Public examples when APIs or behavior change: cargo run -p canwu-reference-world --example starter, cargo run -p canwu-api --example phased_boundary, and cargo run -p canwu-api --example plugin, and cargo run -p canwu-api --example decision_ticket.
• Rust documentation when public types or docs change: cargo doc --workspace --no-deps.
• Standalone performance harness when its workload or reporting changes: cargo fmt --manifest-path benchmarks/performance-harness/Cargo.toml -- --check, cargo clippy --manifest-path benchmarks/performance-harness/Cargo.toml --all-targets --all-features -- -D warnings, cargo test --manifest-path benchmarks/performance-harness/Cargo.toml, and cargo test --manifest-path benchmarks/performance-harness/Cargo.toml --features allocation-counting.