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/fix-slice entries

Triage records its verdict for each issue in the ignored backlog-queue.md working file. fix-now means the issue lands in one review-sized PR. fix-slice means the issue needs a stack, and the entry’s third field is the imperative work statement for the next PR in that stack — fix mode implements exactly that, opens a PR that says Advances rather than Closes, and labels the issue sliced so the following triage pass cuts the next slice. Issues that cannot move without a person are needs-human — the only non-working verdict. Size alone never earns it: work that needs several PRs is fix-slice on its first one. Edit the queue file to change a verdict, or to reword a slice, before fix mode reads it. Triage never closes issues.

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 returned for re-slicing if its reviewable diff exceeds 500 added/deleted lines — the ceiling sizes a single PR for review, so an oversized attempt sends the issue back for a smaller next slice rather than retiring it. 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. Because the implementation agent has no shell, the parent script applies ruff format for it — using the lint image, so the formatter matches the version the gate checks with — before committing. It then requests one adversarial read-only review, which must return VERDICT: PASS. 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 .. On its first mutating run, the script creates the triaged, sliced, 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).

Every verdict is reversible. Re-verdict the line in backlog-queue.md to hand an issue to fix mode anyway — fix mode reads the queue, not the labels — or reclassify from scratch with ./tools/backlog.sh triage <issue>. Naming a single issue always reruns the classifier and clears the stale triaged label first; a bulk pass skips issues it has already classified. Delete the old queue line if you want the new verdict to replace it.

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?