Contributing

Read the repository’s AGENTS.base.md, CONTRIBUTING.md, and design guide before making a design decision. The project favors a small, fast, Scrum-focused tool with plain-text, Git-friendly storage.

For a new command, backend, or report, record the Scrum-related need, why existing functionality is insufficient, and the dependency, persistence, and migration/compatibility impact in the issue or pull request. See the design decision record and stability decisions for the storage boundary.

AGENTS.base.md is the shared contributor and agent baseline. A developer may derive a local AGENTS.md overlay with cp AGENTS.base.md AGENTS.md and append personal tool or environment instructions there. Root-level AGENTS.md, CLAUDE.md, and .claude/ are ignored and must not be committed; project rules that everyone needs belong in the tracked baseline or this guide.

Development loop

Install the managed tools and run the quality gate:

mise install
mise run check

Follow TDD for behavior changes:

1. Red — write a focused test that fails for the missing behavior.
2. Green — implement the smallest change that makes the test pass.
3. Refactor — improve structure while keeping the tests green.

Domain behavior belongs in unit-testable modules under src/; CLI input and output belong in integration tests under tests/. Documentation changes should also build the book locally:

mise run book
mdbook serve

The repeatable unit, integration, doctest, and fuzzing commands are collected in Testing and fuzzing.

See Reproducible builds and releases for the pinned toolchain policy, CI job responsibilities, and locked package verification.

Commit and maintainer review workflow

Keep changes in small, green commits: each commit should build and pass the focused tests that cover it. For cross-cutting work, separate data, service, CLI, and documentation changes where practical. If a change cannot be split without obscuring the behavior, explain the boundary in the pull request.

Before starting a large change, review its acceptance conditions and record the decisions that affect scope, persistence, migration, or release behavior. A destructive or release-related change must include its risk, verification, and recovery steps in the pull request. The primary maintainer records the final decision and any follow-up actions, then runs the strongest applicable checks. This documented fallback preserves traceability and keeps the change reviewable when maintainer capacity is limited.

Security work follows the security policy. The security maintainer owns private intake and coordinated disclosure, while the release maintainer owns versioning, changelog, package, tag, and publication checks. When responsibilities overlap, record the owner of each decision in the security or release record.

Before committing

Run mise run check after the final change. It runs all-feature tests, Clippy with warnings denied, Rust documentation with warnings denied, the mdBook build, and formatting checks. Review the complete diff for unrelated changes, keep dependencies minimal, and write actionable user-facing errors.

Backlog changes are part of the normal workflow: inspect and update the self-hosted .pinto/ board through pinto commands, then verify the result with pinto list or pinto board.

Pull requests

Use a focused branch and describe the motivation, implementation, tests, and documentation changes. Include a related issue or planning reference when one exists. Follow the pull request checklist and keep user-facing documentation in English; localized Fluent resources are the intentional exception.