pr-cli · Will-thom · May 26, 2026 · May 26, 2026
@@ -16,6 +16,8 @@ Stage 1 MVP.
 
 The current release line focuses on deterministic local analysis of Maven report artifacts. It does not require GitHub tokens, CI API access, AI providers, telemetry, or external services.
 
+Stage 1 does not include a native GitHub or GitLab API adapter. GitHub is currently the only platform with first-party project automation and a copyable CI example, while the CLI itself remains provider-agnostic. See [Integrations](docs/integrations.md).
+
 Target Maven baseline:
 
 - Maven 3.9.x.
@@ -35,6 +37,7 @@ Apache's download page currently lists Maven 3.9.16 as the recommended release a
 - Emits human-readable text.
 - Emits stable JSON for CI and agent usage.
 - Provides a versioned demo project with Maven report fixtures.
+- Provides GitHub Actions examples, without requiring GitHub API access at runtime.
 
 ## Install From Source
 
@@ -174,6 +177,7 @@ This is useful for:
 - [Installation](docs/installation.md)
 - [Usage guide](docs/usage.md)
 - [Examples](examples/README.md)
+- [Integrations](docs/integrations.md)
 - [Contributing](CONTRIBUTING.md)
 - [Permission posture](docs/permissions.md)
 - [Testing](docs/testing.md)

@@ -47,6 +47,7 @@ Acceptance criteria:
 - Release tags produce Linux, macOS, and Windows packages with checksums.
 - Security automation runs CodeQL, govulncheck, and dependency review.
 - No network or external service is required for core functionality.
+- GitHub is the only first-party platform with project automation and usage examples; no native provider API adapter ships in Stage 1.
 - Stage 2 and Stage 3 issues exist in GitHub with contributor-friendly acceptance criteria.
 
 Expected confidence: high.

@@ -4,6 +4,8 @@ PR Maven CLI uses a Stage 1 OSS-style GitHub pipeline.
 
 The pipeline is intentionally dependency-light. Core checks do not require Maven, Docker, private credentials, hosted services, or external test infrastructure.
 
+This is project CI, not a runtime provider adapter. The Stage 1 CLI does not call GitHub APIs. Runtime/provider integration scope is documented in [integrations.md](integrations.md).
+
 ## CI Workflow
 
 File: `.github/workflows/ci.yml`

@@ -0,0 +1,46 @@
+# Integrations
+
+PR Maven CLI is local-first in Stage 1.
+
+The core analyzer does not call GitHub, GitLab, CI APIs, hosted services, or AI providers. It reads Maven report artifacts from the local filesystem and emits text or JSON.
+
+## Stage 1 Integration Scope
+
+Current first-party integration surface:
+
+- GitHub repository automation for the project itself.
+- GitHub Actions CI/CD workflows for this repository.
+- A copyable GitHub Actions usage example for Maven failure triage.
+
+Current product/runtime integration scope:
+
+- No native GitHub API adapter yet.
+- No native GitLab API adapter yet.
+- No required provider token.
+- No required network access for Maven report analysis.
+
+This means GitHub is the only platform with official project automation and example coverage today, but the CLI itself remains provider-agnostic in Stage 1.
+
+## Planned Native Adapters
+
+Native PR and CI context adapters are planned for Stage 3.
+
+Planned order:
+
+1. GitHub adapter for changed files and check runs.
+2. GitHub-oriented PR summary and CI workspace output.
+3. GitLab merge request support investigation.
+
+Adapters must stay optional. Local Maven report parsing should continue to work without GitHub or GitLab tokens.
+
+## Contributor Guidance
+
+Before adding a provider integration:
+
+- Keep the provider client behind an interface.
+- Avoid making network access part of core tests.
+- Add fixtures or mocks for provider responses.
+- Preserve the local analyzer contract.
+- Document required tokens and permissions.
+- Keep provider-specific behavior out of parser packages.
+
@@ -65,6 +65,12 @@ go run ./cmd/prmaven why -project demo/multi-module-failure -format json
 
 The JSON contract is designed for CI systems, bots, and coding agents. It includes `summary`, `modules`, and `findings`.
 
+## Provider Integrations
+
+Stage 1 has no native GitHub or GitLab API adapter. The CLI does not need provider tokens and does not call remote PR, check-run, issue, or merge request APIs.
+
+GitHub is the only platform with first-party project automation and a copyable CI example today. For the full integration scope and planned native adapters, read [integrations.md](integrations.md).
+
 ## Demo: No-Failure Fixture
 
 ```bash

@@ -10,6 +10,7 @@ func TestDocumentationCoversInstallationUsageAndExamples(t *testing.T) {
 	files := map[string]string{
 		"README.md":                mustReadFile(t, "README.md"),
 		"docs/installation.md":     mustReadFile(t, "docs/installation.md"),
+		"docs/integrations.md":     mustReadFile(t, "docs/integrations.md"),
 		"docs/permissions.md":      mustReadFile(t, "docs/permissions.md"),
 		"docs/usage.md":            mustReadFile(t, "docs/usage.md"),
 		"examples/README.md":       mustReadFile(t, "examples/README.md"),
@@ -19,8 +20,11 @@ func TestDocumentationCoversInstallationUsageAndExamples(t *testing.T) {
 	assertContains(t, files["README.md"], "[Installation](docs/installation.md)")
 	assertContains(t, files["README.md"], "[Usage guide](docs/usage.md)")
 	assertContains(t, files["README.md"], "[Examples](examples/README.md)")
+	assertContains(t, files["README.md"], "[Integrations](docs/integrations.md)")
 	assertContains(t, files["README.md"], "[Permission posture](docs/permissions.md)")
 	assertContains(t, files["docs/installation.md"], "go install ./cmd/prmaven")
+	assertContains(t, files["docs/integrations.md"], "No native GitHub API adapter yet.")
+	assertContains(t, files["docs/integrations.md"], "GitHub is the only platform with official project automation and example coverage today")
 	assertContains(t, files["docs/permissions.md"], "Do not switch it to private if that would disable branch protection or repository rules.")
 	assertContains(t, files["docs/permissions.md"], "All CI checks")
 	assertContains(t, files["docs/installation.md"], "prmaven version")

@@ -54,3 +54,5 @@ The workflow example at [github-actions/triage-maven-failures.yml](github-action
 - upload JSON output as an artifact;
 - preserve the original Maven failure status.
 
+GitHub Actions is the only first-party CI platform example today. The CLI itself does not call the GitHub API in Stage 1.
+
Original file line number	Diff line number	Diff line change
Expand Up		@@ -54,3 +54,5 @@ The workflow example at [github-actions/triage-maven-failures.yml](github-action
		- upload JSON output as an artifact;
		- preserve the original Maven failure status.

		GitHub Actions is the only first-party CI platform example today. The CLI itself does not call the GitHub API in Stage 1.