Archpilot Reviewer — GitHub Action

Automated architecture governance for every Pull Request.

Archpilot Reviewer is a GitHub Action that runs the Archpilot Review Agent on any architecture document merged via PR. It understands the 5-phase pipeline, scores each artifact 0–100, and posts findings directly as a PR comment.

---

How It Works

1. A PR is opened containing .md architecture documents
2. The Action detects the artifact type — pipeline phase (discovery, requirements, HLD, LLD, review) or standards library document (API, security, ADR, etc.)
3. The Review Agent audits the document against the relevant Archpilot rule, runs a lint pass for vague words and placeholders, and scores it 0–100
4. A structured review comment is posted on the PR with score, severity-ranked findings, and actionable fixes

Gate logic:

• 90–100: Exemplary — PROCEED
• 80–89: PROCEED with minor fixes noted
• 60–79: REVISE — significant gaps
• Below 60: BLOCK — major sections missing

---

Setup

Add this workflow to your repo at .github/workflows/archpilot-review.yml:

name: Archpilot Architecture Review

on:
  pull_request:
    paths:
      - '.specs/**'
      - 'docs/**'

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Archpilot Review Agent
        uses: gauravs19/archpilot-reviewer@v2
        with:
          github_token:       ${{ secrets.GITHUB_TOKEN }}
          anthropic_api_key:  ${{ secrets.ANTHROPIC_API_KEY }}
          rules_repo:         'gauravs19/archpilot'
          specs_path:         '.specs'
          docs_path:          './docs'

---

Inputs

Input	Required	Default	Description
github_token	Yes	—	GitHub token for posting PR comments
anthropic_api_key	No	—	Anthropic API key (recommended)
openai_api_key	No	—	OpenAI API key (fallback)
llm_provider	No	anthropic	anthropic or openai
llm_model	No	claude-opus-4-5	Model ID
rules_repo	No	gauravs19/archpilot	Repo containing Archpilot rules
rules_path	No	rules	Path to rules folder inside rules_repo
specs_path	No	.specs	Path to pipeline artifacts
docs_path	No	./docs	Path to general architecture docs

---

What Gets Reviewed

Pipeline artifacts (5-phase aware)

Filename pattern	Phase	Standard applied
discovery.md	Phase 0 — SE Agent	50-agent-pipeline.md
requirements.md	Phase 1 — PO Agent	50-agent-pipeline.md
Design_HLD.md	Phase 2 — Arch Agent	03-hld-standards.md
Design_LLD_*.md	Phase 3 — Arch Agent	04-lld-standards.md
review_report.md	Phase 4 — Review Agent	50-agent-pipeline.md

Standards library documents

Filename pattern	Standard applied
*api*	05-api-design.md
*security*	07-security-architecture.md
*hld*	03-hld-standards.md
*lld*	04-lld-standards.md
*adr*	02-adr-standards.md
*data*	06-data-architecture.md
anything else	00-architecture-principles.md

---

Review Output Format

Each reviewed file gets a comment block:

## Archpilot Review Agent

### `Design_HLD.md`
**Phase:** Phase 2 — Arch Agent: High-Level Design | **Standard:** `03-hld-standards.md`

#### Lint Findings (auto-detected)
- 🔴 Placeholder detected: `TODO` — must be resolved before merge.
- 🟡 Vague adjective detected: `scalable` — replace with a measurable number.

## Score: 78/100 — REVISE

### Summary
HLD is structurally sound but missing numeric NFR targets and cost model.

### Findings
**🟠 High** — NFR targets are narrative, not numeric.
- **Location:** Section 4 — Non-Functional Requirements
- **Impact:** Unenforceable SLAs; no baseline for capacity planning
- **Fix:** Replace "highly available" with "99.95% uptime, RPO ≤ 1 min, RTO ≤ 15 min"

### What's Working
- C4 diagrams are present and accurate
- ADRs include alternatives considered

---

Contributing

PRs welcome — especially for new artifact type detections, additional rule mappings, and support for additional LLM providers.

Part of the Archpilot ecosystem.

---

Created by Gaurav Sharma — gauravs19.github.io/archpilot

---

Ecosystem

Tool	Description
archpilot	The Enterprise Architecture Standards Library
archpilot-cli	CLI to scaffold architecture documents from the standards library