GitHub
repos · signed webhooks
RigelPlatformHow it works
What's deterministic, what uses a model, and where the gates sit. Written for the engineer who will check.
01 · Architecture
Repos become a chart. The chart briefs agents. Agents' changes go through gates. Rigel centralizes cross-repo application knowledge, workflows, architecture and infra conventions so agents across your estate build consistently.
repos · signed webhooks
issues · signed webhook
you, registering repos
REST, SSE, webhooks, UI
durable workflows
AST · no model
Anthropic API or AWS
+ pgvector · the chart
embeddings · rerank
20 read-only tools
allowlisted tools
fresh clone · allowlist
Claude Code, Cursor…
CI · fixer · review · gates
on GitHub
GitHub, Jira and the UI or CLI feed the web and API server, which dispatches durable workflows on a separate worker tier. Workers build the code graph (no model), call Claude for extraction and analysis, embed text with Voyage AI and write everything to Postgres with pgvector. The MCP server reads Postgres for your coding agents. Rigel's agents read the same chart, change code in a sandbox and open pull requests that the PR Supervisor gates.
Stack: Node.js and TypeScript, a React UI, durable workflows, PostgreSQL with pgvector. Web and worker tiers deploy separately.
find_consumers on the Rigel MCP server..github/** is protected.init, analyze, pr-analyze, query for local one-shot use.Six sources in, six destinations out. Every path runs through the same chart.
02 · Deterministic vs model
Structure comes from code. Models read and write what code analysis can't, and their output is bounded.
No model→ Clone· Discover services· Scan docs· Code graph (AST)· Map dependencies· Extract APIs & channels· 7 analysis passes· OpenAPI (gated)· Voyage AI embedding· Docs PR
Deterministic · uses a model · model output behind a validation gate
| Layer | Technique | Uses a model? |
|---|---|---|
| Service discovery | Filesystem walk of package manifests and monorepo workspaces, classified by Dockerfile, start scripts and entry points | No |
| Internal dependency graph | Manifest dependencies; workspace references become internal edges | No |
| Code graph | AST extraction and community clustering | No |
| Docs scan | Finds existing documentation in the repo | No |
| File classification, risk score | Rules over file paths and a published formula | No |
| Semver and path gates | Parse the manifest diff and the changed-file list | No |
| Inter-service communication | Framework-aware extraction that records HTTP calls, queues and topics, event buses and shared databases | Yes |
| API surface | Framework-aware extraction returning structured endpoint metadata | Yes |
| Infrastructure as code | File discovery (AWS templates, Kubernetes manifests, Helm charts), then model extraction | Both |
| Deep analysis | Seven passes per service: identity, API and data contracts, message and event contracts, business logic, configuration, failure modes, integration manifest | Yes, read-only tools |
| OpenAPI generation | Model generation behind a validation gate. Invalid output never replaces a valid spec | Yes, gated |
| Embeddings, reranking | Voyage AI over endpoints, docs and knowledge | Embedding model |
| Cross-repo synthesis | Integration graph and data-flow narratives per constellation | Yes |
| Capability | Node.js / TypeScript | Java, Kotlin, Python, Go, Ruby |
|---|---|---|
| Service discovery | Shipped | Coming soon |
| Internal dependency graph | Shipped | Coming soon |
| API and channel extraction (model) | Shipped | Only for services found through package.json |
| Seven analysis passes per service | Shipped | Only for services found through package.json |
| Code graph (AST, no model) | Shipped | Depends on the code-graph tool's language support; verify on your repo |
| Docs scan and infrastructure-as-code pass | Shipped | Shipped |
| Package consumer matching | Shipped (npm) | Coming soon |
| Dependency upgrades, semver and path gates | Shipped (npm) | Coming soon |
A repo with no package.json produces no services today, so Rigel won't chart its APIs or find its consumers. A mixed repo gets the full chart for its Node.js services.
03 · Staying current
Only the cells a diff affects are re-analysed.
webhook· idempotency key· triage· re-analyse· advisory lock· rolling docs PR
| Service | 01 | 02 | 03 | 04 | 05 | 06 | 07 |
|---|---|---|---|---|---|---|---|
| orders | ● | ● | ● | ||||
| inventory | |||||||
| notifications | |||||||
| billing-worker |
Passes: 01 identity · 02 API & data contracts · 03 message & event contracts · 04 business logic · 05 configuration · 06 failure modes · 07 integration manifest.
A PR merges on a repo's tracked branch. Repos can opt out.
Keyed on repo and merge commit, so webhook redeliveries don't double-run. One refresh per repo at a time.
An agent on a fixed budget reads the diff against the service inventory and returns the affected (service, pass) cells. When in doubt, it refreshes.
All doc changes for a base branch go to one PR, committed only if a fresh doc was written.
No races: onboarding, refresh and OpenAPI updates take a Postgres advisory lock before writing to the docs PR.
No loops: merges of Rigel's own docs branches don't trigger refreshes.
Branch-aware: snapshots are keyed by repo and branch. Older ones are pruned nightly. Invented pass IDs from triage are dropped.
03b · Trust the chart
Edges come from code, manifests and model extraction. Here's what that guarantees, and what it doesn't.
Package matches read package.json dependencies, so they are exact. Endpoint matches Beta compare recorded HTTP paths, exactly or as patterns. Queue matches Beta compare channel names, ignoring case.
It means nothing in the chart matched. Known blind spots: URLs built at runtime from config or environment, routing done by a service mesh or gateway, topic names read from config, and repos not yet charted.
The chart refreshes on every merge to a tracked branch. A triage agent picks the cells to re-analyse and is told to refresh when in doubt. Re-run Deep Survey on a repo at any time for a full pass; extraction is cached per commit, so unchanged code isn't re-billed. MCP answers can lag the database by up to 5 minutes (context cache). Per-service "last analysed commit" for agents: On our radar.
We haven't published measured accuracy yet. When we have an evaluation we stand behind, we'll show the method and recall/precision per edge type here rather than a headline number.
Repos too large for one workflow run fail fast with a message (1,000-step limit). Onboarding runs one workflow per repo at a time, two globally. Code graph builds time out at 300 seconds. The last 5 snapshots per repo and branch are kept. We'll publish a tested-scale figure once we can back it with real estates.
Deep Survey reads docs already in the repo, including docs/, adr/, decisions/ and rfcs/ folders. Catalog files aren't read; catalog sync is On our radar. The chart lives in your Postgres and the generated docs and OpenAPI specs are committed to your repos, so nothing is locked inside Rigel.
04 · Risk scoring
A transparent heuristic, not a machine-learning model. It doesn't predict incidents; it shows what a change touches.
8 factors · Σ weight 25
| Factor | Weight | Severity thresholds |
|---|---|---|
| Service scope | × 3 | ≥5 affected = critical · ≥3 = high · ≥2 directly changed = medium |
| Cross-service impact | × 4 | any breaking = critical · ≥3 warnings = high · ≥1 warning = medium |
| Database migrations | × 4 | ≥3 migrations = critical · any migration or ORM schema file = high |
| API changes | × 3 | ≥5 endpoints = high · ≥1 = medium |
| Change volume | × 2 | ≥20 source files or ≥1,000 lines = high · ≥10 or ≥500 = medium |
| Configuration changes | × 2 | any CI file, or ≥3 config files = medium |
| File deletions | × 2 | ≥5 = high · ≥2 = medium |
| Destructive schema changes | × 5 | deleted schema file, or ≥2 schema/migration files with net deletions = critical · 1 = high |
score = round( Σ(severity × weight) / Σ(weight) × 100 ) severity low 0.1 · medium 0.4 · high 0.7 · critical 1.0 level ≥70 critical · ≥45 high · ≥25 medium · else low
All factors low scores 10 (low). Only non-low factors appear in the PR comment.
Worked examples: docs-only stays low; a new endpoint reaches medium; a shared-DB migration reaches critical.
Changed files → classify each (source, test, config, CI, migration, schema, docs) and map it to a service → walk the dependency graph for transitive impact → detect cross-service impacts → score.
API and contract factors depend on the endpoints and channels recorded at onboarding. Destructive schema changes are a proxy (net line deletions in schema or migration files); SQL isn't parsed.
05 · How agents run
Agents run without interactive approval prompts, so the tool surface Rigel builds is the boundary.
An agent's tools are the intersection of what its template declares and what the operator allows, minus hard-banned built-ins.
Also banned: WebSearch · WebFetch · Agent.
Agents that edit code get a sandbox tool, not a shell: a fresh clone, allowlisted first commands, no shell interpreter, lifecycle scripts off, capped output, time and command count.
Guard-railed, not hermetic: allowlisted tools such as node can still run code. Security & Trust has the detail.
.github/**The checks an agent is judged by can't be edited by the agent. Refused three ways, fail-closed:
Runs also have turn caps. Every run is a retryable, idempotent workflow step, so a pod restart doesn't lose work.
If these critics error, your work continues.
If these critics error, nothing is written or sent.
06 · Which PRs get what
The honest version, by PR author.
Rigel merges only inside your branch protection. Major upgrades, CI paths and PRs titled [needs-review] always wait for a person. Every default →
| PR opened by | Impact analysis, persona review | PR Supervisor gates, Repo Guard, Flight Log | Auto-merge |
|---|---|---|---|
| Rigel's own agentsbug triage, dependency advisors, docs refresh, @mention re-fix, operator-run playbooks | Yes, when enabled for the repo | Yes | When the origin's gates pass (bug-triage PRs never auto-merge) |
| Your other coding agentsClaude Code, Cursor, Copilot agent and others | Yes, when enabled for the repo | Not today Coming soon | No; your team merges |
| People | Yes, when enabled for the repo | No | No; your team merges |
Poll checks, statuses and review threads on a time budget separate from the fix cap.
Green, failing, pending, no CI or blocked. Fixable failures get the PR Fixer, 4 iterations at most.
After a fix to code, request a fresh GitHub Copilot review and wait for it. No merge while it's pending.
CI exists and is green, no unresolved threads, not a draft, and the opening flow allows auto-merge.
For dependency PRs: needs-review brake, semver gate and path gate. A held green PR gets a decision comment.
Rigel doesn't require a human approval itself. If your branch protection requires reviews, merges wait for them, and we recommend requiring them. If a human merges or closes the PR, the supervisor stands down.
Auto-merge on green is on by default for supervised flows except bug triage. Docs-only PRs may merge in repos with no CI.
The upgrade advisors have a separate playbook-level "auto-merge on green" setting, off by default. When on, the advisor merges through its own merge tool, which refuses drafts, changes-requested reviews, unmergeable PRs, PRs with no CI and [needs-review] titles, but doesn't run the semver and path gates. Leave it off to keep every dependency merge behind those gates.
Lifecycle events go to Slack, one thread per PR; a PR that needs a human gets a "Human action needed" alert with the reason.
07 · Models & integrations
Opus, Sonnet and Haiku, selectable per deployment. Use the Anthropic API, or Claude through your own AWS account. Multi-turn agents run on the Claude Agent SDK; single-turn calls retry with backoff.
Repos, PR webhooks, docs PRs and merges. One token today; GitHub App Coming soon.
Connect over MCP for 20 read-only tools.
Required as reviewer for code-change auto-merge; without it, a person merges.
9 PR lifecycle events, one thread per PR, through your Slack MCP server. Slack app Coming soon.
Signed webhooks start bug triage; one comment back per bug.
Publishes requirements, solution designs and release docs. Off by default.
Claude through your AWS account, plus read-only ops tools for logs, metrics and deploy pipelines.
Claude models on your key.
Code embeddings for semantic search; code excerpts are sent to Voyage on your key.
Register stdio or HTTP servers; per-agent allowlists.
Failed workflows triaged into a fix PR and one Slack message.
Agent2Agent registry and a depth-capped mesh.
GitLab and Bitbucket: on our radar.
08 · What ships today
Shipped has no badge. Beta works but is still changing. Coming soon is not available yet. "On our radar" means listening, not committing.
Last updated 1 October 2026
| Dimension | Today | Next |
|---|---|---|
| Code host | GitHub (one deployment-wide token) | GitHub App Coming soon; other hosts: On our radar |
| Languages, full chart | Node.js / TypeScript (details) | Java, Python, Go Coming soon |
| Package ecosystem for upgrades | npm | Other ecosystems Coming soon |
| Model provider | Claude via the Anthropic API or your AWS account | Per-workspace keys Coming soon |
| Embeddings | Voyage AI (required) | In-boundary option: On our radar |
| Reviewer of record for code-change auto-merge | GitHub Copilot code review | Pluggable reviewer Coming soon |
| PRs Rigel can gate and merge | PRs from Rigel's own agents | Any coding agent's PRs Coming soon |
| Deployment | Self-host on Kubernetes or Docker Beta | Rigel Cloud, Helm chart Coming soon |
| Module | Capability | Status |
|---|---|---|
| Map | Deep Survey (seven passes per service) Node.js / TypeScript | Shipped Coming soon · Java, Python, Go |
| Map | Code graph optional component | Shipped |
| Map | Constellations and assembly | Shipped |
| Map | Visual cross-repo constellation map | Coming soon |
| Map | Branch-aware chart | Shipped |
| Map | Living Docs: refresh on merge, rolling docs PR | Shipped |
| Map | OpenAPI on merge opt-in per repo | Shipped |
| Map | Semantic search needs Voyage AI | Shipped |
| Map | Self-learning knowledge base | Beta |
| Map | Ask Rigel | Shipped |
| Map | IDP catalog sync | On our radar |
| MCP | 20 read-only tools over stdio | Shipped |
| MCP | HTTP transport (in-cluster, no built-in auth) | Beta |
| MCP | Hosted, authenticated endpoint with Rigel Cloud | Coming soon |
| Impact | Blast radius and risk score on PRs enable per repo; any PR author | Shipped |
| Impact | Persona review enable per repo | Shipped |
| Impact | Cross-repo consumers: packages, via MCP and agents package.json manifests | Shipped |
| Impact | Cross-repo consumers: endpoints and queues, via MCP and agents being hardened | Beta |
| Impact | Cross-repo consumers in the PR comment; Cross-Repo Impact screen | Coming soon |
| Impact | GitHub Action not on the Marketplace | Beta |
| Impact | Daily Deploy Risk Digest needs an operator-registered GitHub MCP server | Shipped |
| Impact | Release Analysis (change-approval pack) AWS release pipelines; other CD systems on our radar | Shipped |
| Autopilot | PR Supervisor with origin-aware gates, for PRs Rigel's agents open GitHub; Copilot review for code changes | Shipped |
| Autopilot | Supervision of PRs from other coding agents not available today | Coming soon |
| Autopilot | Per-org configurable merge policies | Coming soon |
| Autopilot | PR Fixer and @mention re-fix | Shipped |
| Autopilot | Playbooks (on a schedule you set, or on demand) | Shipped |
| Autopilot | Dependency Upgrade Advisor npm on GitHub | Shipped Coming soon · Maven/Gradle, pip/Poetry, Go modules |
| Autopilot | Lib Version Bump Advisor | Beta |
| Autopilot | Jira Bug Triage Jira Cloud; PRs never auto-merge | Shipped |
| Autopilot | Temporal failed-workflow triage | Beta |
| Autopilot | Workflow Builder v1 limits | Shipped |
| Autopilot | Agent Builder | Shipped |
| Autopilot | A2A agents, mesh, self-hosted agent host | Beta |
| Autopilot | Flight Log (Slack) one workspace | Shipped |
| Autopilot | Repo Guard (installed by you from our template) | Shipped |
| Autopilot | Ops Debug Agent, Staging Alarm Triage AWS | Shipped |
| Autopilot | Feature autopilot (agents build solution tasks) | Coming soon |
| Autopilot | Unified audit export | Coming soon |
| Plan | Requirement Brief, Solution Course | Shipped |
| Plan | Versions, share links, export | Shipped |
| Plan | Confluence push off by default | Beta |
| Security | Read-only Postgres MCP boundary (eight layers) | Shipped |
| Security | Leakage critics (knowledge base, A2A) | Beta |
| Security | Hermetic sandbox (container isolation, minimal environment) | Coming soon |
| Platform | Rigel Enterprise (self-host) | Beta |
| Platform | Helm chart, licence keys, air-gapped install | Coming soon |
| Platform | Versioned database migrations | Coming soon |
| Platform | Rigel Cloud (multi-tenant SaaS) | Coming soon |
| Platform | Per-tenant bring-your-own Anthropic key | Coming soon |
| Platform | Per-org single sign-on and roles | Coming soon |
| Platform | Single sign-on via your OpenID Connect identity provider (one realm) required for any shared deployment | Shipped |
| Platform | Budget caps per run, chat query and drafting session; cost tracking; admin usage | Shipped |
| Platform | Organisation-level spend caps | Coming soon |
| Platform | Billing | Coming soon |
Next, in order
We'll add dates here when we commit to them.
09 · Under the hood
Real config, real arguments, real rules.
.mcp.json · project root · Claude Code / Cursor
{
"mcpServers": {
"rigel": {
"type": "http",
"url": "https://rigel-mcp.internal.example/mcp"
}
}
}
# tools (read-only)
# list_repositories · get_service_info · get_dependency_graph
# get_api_surface · get_communication_channels · semantic_search
# find_consumers · cross_repo_impact · get_callers · get_callees
# get_imports · get_class_hierarchy · get_subgraph · …
One entry gives your agent the whole chart. Read-only by contract: no tool on this server can write. Remote over stateless Streamable HTTP at /mcp, or stdio locally. Run the remote endpoint inside your network until endpoint auth ships. Hostnames are examples.
find_consumers · MCP tool call · JSON
// request { "name": "find_consumers", "arguments": { "source_repository_id": "orders-api", "package_names": ["@your-org/orders-client"] } } // result [ { "repository": "fulfillment", "service": "fulfillment-service", "matchType": "package", "severity": "warning", "reason": "depends on @your-org/orders-client" }, { "repository": "billing", "service": "billing-worker", "matchType": "package", "severity": "warning", … } ]
Ask who breaks before you change it. Matches a change against every onboarded repo's snapshot by package, endpoint or queue. Package matching is exact; endpoint and queue matching are Beta. Severity is info or warning, never a guess at "breaking".
risk-scorer.ts · core/analysis
const WEIGHTS = { serviceCount: 3, crossService: 4, migrations: 4, schemaDestruction: 5, apiChanges: 3, changeVolume: 2, configOrCi: 2, deletions: 2, }; // severity ∈ {0.1, 0.4, 0.7, 1.0} score = Σ(weight × severity) / Σ weight × 100 // ≥ 70 critical · ≥ 45 high · ≥ 25 medium · else low
A heuristic you can read, not a model. Eight weighted factors, each graded on a four-step severity scale. The PR comment shows every factor that moved the score.
merge gates · orchestrator/activities · dependency-advisor origin
pathGate(files) allow **/package.json · lockfiles · e2e-tests/** deny .github/ · .aws/ · template.yaml · .gitmodules semverGate(manifestDiff) patch | minor → merge internal major ∧ sole change ∧ ¬denyList ∧ title starts "[major]" → merge external major | downgrade | prerelease | added / removed dep | unparseable → hold brake(title) "[needs-review]" → hold # always wins on hold of a green PR → upsert decision comment
Deterministic gates, re-derived from the diff. The supervisor never trusts the agent's own summary: it re-reads every changed manifest between merge-base and head. Per-org policies are coming soon; today the policy is in code.
sandbox policy · core/sandbox/bash-sandbox.ts
sandbox: clone: shallow, token-scoped, /tmp/rigel-sandbox-* commands: [npm, npx, pnpm, yarn, knip, node, git, …read/text tools] rejected: ["$(", "`", path escapes outside the clone] env: npm_config_ignore_scripts: 1 limits: per_command: 5m # 2m default commands: 200 output: 16KB protected: - ".github/**" # write time · pre-push diff · pre-push hook
A sandbox tool, inside a fence. Code-changing agents get a sandbox tool, not a shell: a shallow clone, a first-token command allowlist and no shell interpreter. It reduces risk but is not a VM: allowed tools can still execute code, so pair it with branch protection.
10 · Glossary
| Term | In plain words |
|---|---|
| Chart | The service dependency graph Rigel builds from your code. |
| Constellation | A group of related repos that make up one application. |
| Deep Survey | The 7-pass analysis Rigel runs on each service. |
| Blast radius | What else a change can affect. |
| PR Supervisor | The gates that decide whether a PR from Rigel's own agents merges or waits for a person. |
| Flight Log | One Slack thread per agent PR, from open to merge. |
| Requirement Brief | Turns a one-line ticket into a sign-off-ready requirement. |
| Solution Course | A solution design and task breakdown grounded in the chart. |
| MCP | Model Context Protocol, the standard way AI agents call outside tools. |
| PR | Pull request: a proposed code change, reviewed before it merges. |
| CI | Continuous integration: the automated tests and checks that run on every PR. |
| Beta | Works, but still changing. |
| Coming soon | Not available yet. |
We'll trace one of your repos from onboarding to a governed PR.