Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing

Thank you for your interest in contributing to the Pretorin CLI!

We welcome contributions to the CLI, MCP server, docs, scanners, developer workflows, and local tooling. This repository is open source under Apache-2.0, while Pretorin-hosted platform services, authenticated API access, and account-scoped data are governed separately by the applicable platform terms.

Scope

Good fits for this repository:

  • CLI commands and output improvements
  • MCP tools, prompts, and local agent integrations
  • Scanner integrations and developer workflow automation
  • Documentation, examples, and tests

Out of scope for public contributions:

  • Customer data, exported platform data, or private operational runbooks
  • Secrets, internal credentials, or private environment details
  • Changes that imply trademark rights or suggest an unofficial fork is an official Pretorin service

For brand usage guidance, see Trademarks and Service Terms.

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/pretorin-cli.git
cd pretorin-cli
  3. Install development dependencies: 
    uv pip install -e ".[dev]"

Development Workflow

Running Tests

pytest

Integration tests require an API key and are marked with @pytest.mark.integration:

pytest -m integration

Integration tests require a valid API key tied to an account that has accepted the platform terms.

Type Checking

mypy src/pretorin

Linting

ruff check src/pretorin
ruff format src/pretorin

Full CI Check

Run the same checks as the CI pipeline:

ruff check src/pretorin && ruff format --check src/pretorin && mypy src/pretorin && pytest

Autonomous Backlog Triage

tools/backlog.sh turns well-scoped, open GitHub issues into independently reviewable PRs. Only unassigned issues and issues assigned exclusively to the authenticated gh user are eligible; an issue with any other assignee is skipped again before fix mode starts work. Triage and implementation are deliberately separate so a human can review the cheap classification pass before any code is written.

./tools/backlog.sh status        # queue and work in flight; read-only
./tools/backlog.sh triage 123    # classify one issue as a sanity check
./tools/backlog.sh triage        # classify open issues eligible for this user
./tools/backlog.sh fix           # work approved fix-now entries one at a time

Triage records fix-now and needs-human entries in the ignored backlog-queue.md working file. It labels features, epics, ambiguous work, and changes over the review ceiling as too-large. It may close only app/github-actions issues for which a later successful run of the same workflow is supplied and independently verified. Edit the queue file to change a verdict before fix mode reads it.

Fix mode claims one issue with agent-wip, creates a dedicated worktree and backlog/issue-* branch from origin/master, then asks a sandboxed agent for a focused implementation and regression test. The parent script—not the issue- reading agent—owns Git, GitHub writes, commits, pushes, and PR creation. The implementation is rejected if its reviewable diff exceeds 500 added/deleted lines. Generated docs/book/ files, lockfiles, snapshots, and fixtures do not count toward that ceiling. CI, tooling, dependency manifests, project agent instructions, Docker configuration, and generated-doc paths are human-only; the loop rejects agent edits to them.

Before opening a PR, the script rebuilds and verifies the mdBook output, then runs Ruff, mypy, and pytest with coverage against a read-only worktree mount in network-isolated Docker containers. The dependency audit runs in a separate credential-free container. It then requests an adversarial read-only self-review and runs an independent codex review when Codex is installed. Integration tests are excluded because they require a platform API key and run after merge. Failed gates leave the worktree under .claude/worktrees/backlog-<issue>/ for inspection.

Prerequisites are authenticated gh and claude CLIs, Python 3, Docker, and mdBook 0.5.2 with the pinned Rust 1.94.1 toolchain. Build the trusted gate images from master before fix mode with docker build --target lint -t pretorin-cli-lint:latest . and docker build --target test -t pretorin-cli-test:latest .. Codex is optional. On its first mutating run, the script creates the triaged, too-large, and agent-wip repository labels if needed. Logs are written to logs/backlog/.

Tune the loop with BACKLOG_WIP_CAP (default 3 open backlog/* PRs), BACKLOG_MAX_LOC (default 500 reviewable lines), and BACKLOG_MAX_ITERATIONS (default 25).

Submitting Changes

  1. Create a feature branch from master
  2. Make your changes
  3. Ensure tests pass and code is properly formatted
  4. Add a sign-off to each commit with git commit -s
  5. Submit a pull request

By submitting a contribution, you certify that:

  • You have the right to submit the code, docs, or other materials.
  • Your contribution may be distributed under the Apache License, Version 2.0.
  • You are not including confidential information, customer data, or material that is governed by separate platform terms.

Code Style

  • Follow PEP 8 guidelines
  • Use type hints for all function signatures
  • Write docstrings for public functions and classes
  • Keep functions focused and small

CI Pipeline

The CI pipeline runs on Python 3.10, 3.11, and 3.12:

  • Lint — Ruff check + format
  • Audit — pip-audit (dependency vulnerability scan)
  • Type check — mypy strict mode
  • Test — pytest
  • The source code in this repository is licensed under Apache-2.0.
  • The Pretorin name, logos, and other brand assets remain subject to trademark rights and are not licensed for reuse except for nominative/reference use. See Trademarks and Service Terms.
  • Access to Pretorin-hosted APIs, services, and account-scoped data is authenticated and governed by separate platform terms.

Reporting Issues

Use GitHub Issues to report bugs or request features. Include:

  • Clear description of the issue
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • CLI version (pretorin version)

Questions?