Skip to content

Contribute to AWC

The implementation backlog in to-do.json is the canonical work queue. This guide builds the workspace, picks a task, writes code to the repo style, and runs the gate before you propose the change.

Spec reference

The reference technology choices, repo layout, and build are spec §22.1, §22.3, and §22.11.

  1. Build the workspace.

    make build

    make build runs cargo build --workspace --all-targets. The toolchain is Rust 1.94.0, pinned by rust-toolchain.toml with rustfmt and clippy. Install cargo-deny for the dependency audit:

    cargo install cargo-deny

  2. Read the backlog contract.

    AGENTS.md defines how project work runs. to-do.json is the single source of truth for implementation work, and to-do.schema.json validates it. The backlog is implementation-only. Read every document listed under source_files before you start.

  3. Pick the next task.

    Choose the lowest-numbered priority task with status todo, breaking ties by lexicographic id:

    jq '.tasks | map(select(.status == "todo")) | sort_by(.priority, .id) | .[0]' to-do.json

    Check the task depends_on list. Every dependency MUST be done before you start. Set the task to doing and update updated_at before you write code.

  4. Write code to the repo style.

    • Run make fmt to format in place. The config is edition = "2021" and max_width = 100.
    • Keep new crates #![forbid(unsafe_code)]. The manifest library MUST expose no unsafe deserialization path for untrusted objects (spec §22.4).
    • Clippy warnings are errors. Run make lint (clippy --workspace --all-targets -- -D warnings).
    • All components MUST consume the same versioned manifest library and test vectors (spec §22.2).

  5. Write docs in Simplified Technical English.

    Prose and doc pages follow docs/.style-guide.md. Keep sentences under 20 words. Spell out Latin abbreviations. The forbidden-words list applies to every page, including this one.

  6. Run the CI gate.

    make ci

    make ci is fmt-check plus lint plus test plus deny. GitHub Actions runs the same checks, then adds a production-feature compile and the service-backed suites (make ci-pg, make ci-s3). See run the test suite for those suites.

  7. Propose the change.

    Write commits in the conventional style the history already uses, for example fix(awc-fuse): permit root on the read-only basefs FUSE mount. When the task is complete, set it to done, update updated_at, and record paths in files or outcomes in details. Keep to-do.json at two-space indentation and valid against the schema. Open a pull request. The CI workflow MUST pass before merge.

Scope discipline

AWC is an agent workspace cache: snapshot → fork → mount → checkpoint → diff/export. Do not add a general filesystem, a sandbox, an agent scheduler, or a build cache (spec §3.2, §4.2, §26.12). Work that is deferred, not committed, is listed in spec §27.

See also