cabin

# AGENTS.md

Cabin is a pre-1.0, Cargo-inspired, but not Cargo-compatible, package manager
and build system for C/C++, implemented in Rust. Use Cargo vocabulary only
when the C/C++ semantics match.

`docs/architecture.md` is authoritative for architecture, crate ownership,
data flow, and scope exclusions. If it conflicts with this file, update both
in the same change and follow the architecture document.

## Scoped instructions and canonical docs

- Read `crates/AGENTS.md` before changing `crates/`. Before changing
  `crates/cabin/`, also read `crates/cabin/AGENTS.md`.
- Read `registry/AGENTS.md` before changing `registry/`; it routes registry
  work to the owning module and names the registry-specific checks, which
  `cargo ci` does not cover.
- Read `website/AGENTS.md` before changing `website/`, `docs/`, or `ports/`;
  those paths share the website verification gate. `docs/` contains the
  canonical Markdown rendered by the website.
- Read `.github/AGENTS.md` before changing GitHub Actions workflows or other
  `.github/` configuration.
- Use `RELEASING.md` for release procedure. Do not infer release policy from
  CI or change binstall, publishing, or release workflows during
  unrelated work.

## Working rules

- Resolve incompatible interpretations before coding. State any assumption
  that materially affects the result.
- Do not modify `AGENTS.md` unless explicitly requested, or unless the current
  change would otherwise make an existing instruction factually incorrect.
- Make the smallest coherent change required. Do not refactor, reformat,
  clean up, or remove unrelated code, including pre-existing dead code.
- Prefer existing repository mechanisms and maintained upstream tools,
  libraries, and platform features over repository-owned replacements. Do not
  reimplement or compatibility-port third-party semantics merely to remove a
  dependency, runtime, or implementation language.
- If exact behavioral parity with an external tool is required, use that tool
  as the source of truth rather than cloning its behavior. Owning a replacement
  parser, linter, formatter, protocol implementation, or compatibility layer
  requires explicit maintainer approval.
- Reuse existing code and patterns. Within Cabin-owned Rust code, prefer
  direct implementations over speculative abstraction, configuration, or
  flexibility.
- Before finalizing a change, review the complete diff for code,
  configuration, helpers, files, or dependencies that can be removed or
  simplified without changing the intended behavior.
- Treat review comments as findings to evaluate, not requirements to
  implement. Fix security issues, supported-path correctness bugs, and
  documented contract violations. Do not expand the design solely to handle
  speculative edge cases or make behavior theoretically complete.
- Complexity must be proportional to the failure being prevented. Do not add
  state, reconciliation, lifecycle tracking, or cleanup machinery for rare
  combinations of transient failures unless they can cause a security issue,
  data loss, or a realistic user-visible correctness failure.
- Prefer reducing the state space or simplifying an invariant over adding
  logic to make every possible state behave perfectly. Once supported
  behavior is correct and secure, stop.
- Comments explain non-obvious constraints, compatibility requirements, or
  rationale. Do not restate mechanics that clearer code can express.
- Do not implement features listed as deferred or "not implemented" in
  `docs/architecture.md`. Unknown future syntax must use generic
  `deny_unknown_fields` or clap unknown-flag diagnostics, not tailored
  rejection arms.
- Keep C first-class alongside C++. Changes to planning, manifests, flags,
  toolchains, Ninja output, packaging, lockfiles, metadata, and related docs
  must cover both languages, including fixtures.
- Keep generated and machine-readable output sorted or normalized. See
  `docs/architecture.md` "Contributor-facing architecture guardrails" for
  the affected outputs.
- Add focused tests that detect a concrete behavioral regression. Prefer the
  lowest useful layer; add CLI integration coverage when end-to-end behavior
  itself is the contract, not to duplicate unit coverage. Do not test
  implementation text/layout, trivial derived behavior, or library/framework
  guarantees. Follow the portability rules in `crates/AGENTS.md`.
- Tests must not read `.github/` files or depend on a workflow path. Workflow
  moves or renames must not break the test suite.
- Scripted or repeated edits must verify that the expected pattern matched
  and the old form is gone.
- Claim verification only when an executed check could have detected the
  relevant failure. Report checks run and any relevant checks skipped.
- Do not edit `typos.toml` or add allowlist entries unless a reviewer asks;
  fix the spelling.

## Cabin invariants

- `--target` is reserved for future platform/toolchain triples. Do not use it
  for manifest-target selection. The build-output flag is `--build-dir`;
  `--target-dir` is not an alias.
- A port directory is published verbatim, so every edit, including a comment,
  changes archive bytes. Compare its published digest before editing and do
  not fold a port correction into unrelated work. Follow
  `docs/foundation-ports.md` "Packaging revisions" for which corrections may
  respin as a packaging revision and which need a new upstream version; the
  temporary-registry preflight cannot validate this distinction.

## Repository automation

- Cabin-specific repository automation and orchestration belongs in private
  Rust `crates/xtask-*` crates run through cargo aliases; see
  `crates/AGENTS.md` "Repository automation (xtasks)".
- Do not reintroduce shell or Perl repository tooling. This restriction does
  not cover product or website source, npm scripts, `Dockerfile`, `demo.tape`,
  devcontainer provisioning, or normal invocation/configuration of external
  tools.

## Checks

- Run `cargo ci` from the repository root. It scopes expensive checks to
  changes relative to `origin/main`.
- Changes under `docs/`, `website/`, or `ports/` require the website gate
  defined in `website/AGENTS.md`. `cargo ci` runs it for those paths; run it
  manually if site output changes through another path.
- Changes under `registry/` require the registry checks listed in
  `registry/AGENTS.md`; `cargo ci` does not run them.
- Commit-message policy follows `@commitlint/config-conventional`; treat
  upstream commitlint behavior as authoritative. The generated squash-merge
  header must remain within its 100-character limit.

## Documentation sync

- Update the matching `docs/` page with user-visible behavior or architecture
  changes.
- Update `website/` in the same change, or identify the required follow-up,
  when changing product positioning, supported languages or platforms,
  installation, top-level commands, or package-page snippets.
- Migrations and removals can stale descriptions outside the code path.
  Check `docs/`, `CONTRIBUTING.md`, each affected example README and
  `examples/README.md`, `ports/README.md`, and website copy. Update claims
  about the repository's current shape; leave durable upstream facts and
  policy alone.

## Git and pull requests

- All implementation work uses a branch and PR; never implement directly on
  the default branch. Before editing, inspect status, update the default
  branch from its remote, and create a fresh branch. Preserve all unrelated
  local changes: do not discard, reset, overwrite, or commit them.
- Use one branch per PR. Each PR must be the smallest cohesive change that is
  independently buildable, testable, and reviewable. Split independent
  changes by default; keep changes together when a split would leave a
  broken, untestable, unsafe, misleading, or meaningless intermediate state.
- If work needs multiple PRs, state their order and responsibility. Handle
  dependent PRs sequentially: do not start or open a later dependent branch
  or PR until the current PR has no blocking review findings, is green,
  squash-merged, and the local default branch is updated. Independent PRs may
  overlap in time only when they do not overlap in scope.
- Before opening or updating a PR, run the relevant checks and report their
  results. Fix failures caused by the change.
- Open a PR as one cohesive commit; its subject becomes the PR title. Once a
  PR is open, land review feedback, CI failures, test corrections, and small
  omissions as ordinary commits on top, within the PR's scope. Do not rewrite
  pushed commit history to prepare a PR for squash merge.
- After any content change, obtain a fresh review of the updated PR before
  merge.
- If you have permission, squash merge once the latest review reports no
  blocking findings, required checks pass, and all review comments and
  requested changes are resolved. Resolving a review comment does not imply
  implementing it: reject findings that are incorrect, speculative, out of
  scope, or disproportionately complex, with a concise rationale. Delete the
  merged branch.

More agent context in cabinpkg/cabin

4 other files this repository gives its agents.