Skip to documentation
Conformative documentation

Understand, run, and extend the truth layer for agent-built software.

Conformative derives a single map connecting product intent, implementation, stack, and drift. This guide covers private-preview onboarding, the implemented pre-release local interface, product surfaces, tool contracts, security posture, and availability.

Local first

The account-free embedded runtime is implemented; its public npm release is pending.

Evidence first

Every conclusion is tied to a scan, revision, graph, or spec.

Humans approve writes

Repository changes are proposals until a person authorizes them.

Get started

Private-preview quickstart

Hosted access is available to invited and allowlisted teams. The local CLI is implemented and release-tested, but its npm package is not public yet—do not install similarly named packages.

Hosted private preview

Sign in with the approved GitHub identity, install the Conformative GitHub App, and choose the repositories the preview may observe.

Open Conformative

Local CLI release

Package publication is intentionally gated while final installation testing is completed. This page will publish the verified npm command at release.

npm package · not public yet
  1. 01

    Sign in

    Use the GitHub identity approved for the private preview.

  2. 02

    Connect GitHub

    Install the App and select the repositories to observe.

  3. 03

    Confirm intent

    Accept or decline discovered PRD and Spec Kit sources before the first scan.

  4. 04

    Build the first map

    Run the exact-head scan, then review health, coverage, drift, and next actions.

First trustworthy result

A project is not shown as clear until a successful full scan has complete enough component, policy, detector, and intent coverage. Partial, stale, failed, or never-scanned evidence stays visibly uncertain.

Mental model

One domain model, one event spine

Each surface is a different view or detector over the same repository truth. The architecture deliberately avoids feature-specific copies of features, graphs, policies, or drift.

01

Intent

Feature + SpecLink

What the product promises.

02

Implementation

Component + Edge

What the code actually contains.

03

Stack

StackProfile + PolicyRule

What the system relies on and allows.

04

Drift

DriftEvent + ProposedChange

Where evidence and claims diverge.

Detectors emit only DriftEvent. Repository fixes flow through ProposedChange. Approval records authorization; only repository evidence and a confirming scan can establish a merge and resolution.

Feature 01

Driftguard

Driftguard compares repository reality with normalized claims from agent context files. Deterministic checks run without an LLM; optional semantic analysis works over minimal derived context.

Detect

Finds context, stack, version, and documented-convention mismatches at a known revision.

Reconcile

Re-observation is idempotent, dismissals survive, and resolution requires adequate detector coverage.

Propose

Generates a reviewable patch or PR handoff. It never bypasses human approval.

Feature 02

Cockpit

Cockpit turns the shared model into a PM-legible operating surface. It presents uncertainty explicitly and keeps every decision linked to its underlying evidence.

Overview

Safety verdict, freshness, coverage, recent change, and ranked next actions.

Map

Architecture areas first, then files, symbols, relationships, intent, owners, policies, and risk.

Risks

Filterable context, intent, stack, and policy drift with status history and proposals.

Features

Confirmed product intent, accepted implementation links, conformance, and archival.

Trends

Transition-backed opened/resolved history, MTTR, and scan-health evidence.

Ask

Constrained questions over features, current drift, and history—never free-form SQL.

Feature 03

Conformance

Conformance asks whether accepted implementation still satisfies confirmed product intent. It reuses the same graph, event, proposal, transition, and notification machinery as context drift.

Spec → code

A promised capability is missing or not supported by linked implementation evidence.

Code → spec

The implementation contains a meaningful capability the current spec does not describe.

Feature 04

Guardrail MCP

Guardrail gives coding agents a project-scoped read of the same map before they change code. Local stdio is part of the Community workflow; managed remote transport is called out separately.

Local MCP

Project-aware tools over stdio, installed by the CLI for supported agent clients.
Pro

Remote MCP

Token-authenticated, organization-confined Streamable HTTP with hosted usage metering.

Operate

The surfaces around the core loop

Later product surfaces add timing, delivery, intake, and editor context without inventing new truth models.

Gatekeeper

Evaluates pull requests before merge and reports a GitHub check without persisting preview findings as project truth.

Intake

Derives Features from confirmed PRDs, Spec Kit sources, and labeled GitHub issues.
Pro

Signals

Delivers newly opened drift and digest rollups from the shared event spine.

Timeline

Records exact drift status transitions for trends, auditability, and history-aware questions.
Pro

Storyline

Plays back a derived, accessible project or feature history without hiding the underlying beats.

Instrument

Brings health, features, drift, blast radius, and entitled approvals into VS Code.

Plans

Feature availability

Pro labels appear here to make deployment and plan choices explicit. Detectors remain plan-agnostic; hosted entitlements gate managed-service invocation.

CommunityComplete local workflow or generally available core surfaceProEntitlement-gated managed or advanced surface

Driftguard

Community

Context-file drift detection and reviewable corrective changes.

Cockpit

Community

Evidence-backed overview, semantic map, risks, features, trends, and policies.

Conformance

Community

Intent-to-implementation checks over confirmed product specifications.

Guardrail MCP · local

Community

Blast radius, stack policy, context, and proposed context updates on your machine.

Continuous hosted scans

Pro

Webhook-driven and hourly reconciled scans of connected GitHub projects.

entitlement: continuous_scans

Remote Guardrail MCP

Pro

Organization-scoped MCP over the managed HTTP transport.

entitlement: remote_mcp

Managed semantic analysis

Pro

Hosted LLM-assisted claim normalization, spec linking, and intent verdicts over derived context.

entitlement: semantic_analysis

Approval workflows

Pro

Review and decide proposed changes from the API and Instrument.

entitlement: approvals

Storyline

Pro

A playable, feature-scoped history derived from scans and drift transitions.

entitlement: story

Signals notifications

Pro

Instant and digest notifications from the shared drift event spine.

entitlement: notifications

Audit history

Pro

Append-only organization history for consequential user, token, and system actions.

entitlement: audit_history

Hosted allowances

Community: 1 project, 1 seat, 25 scans/month, no remote MCP calls.

Pro: 25 projects, 10 seats, 5,000 scans/month, 50,000 MCP calls/month.

Reference

CLI commands (pre-release)

This is the implemented local CLI surface. Its npm package is not public yet; these commands become available when the verified package is published.

Conformative CLI command reference
CommandPurpose
start [--no-open]Start the daemon, database, Cockpit, and guided first run.
add <path>Register, scan, and wire a project into supported tools.
scan <name> | --allRun a serialized full scan at an immutable local snapshot.
listShow tracked projects and recorded drift counts.
mcp [name]Start the project-scoped stdio MCP server.
doctorRead-only diagnostics for the runtime, projects, hooks, and MCP wiring.
remove <name> [--purge]Unwire and stop tracking one project.
stopStop the daemon and its Cockpit child.
uninstall --yesRemove Conformative-owned hooks, MCP entries, and local state.

Reference

MCP tools

Every tool resolves a repository inside the authenticated organization or local project scope. Policy denials can join the same event stream; repository writes still become proposals.

blast_radius

Traverse graph edges from a file or `path#symbol` and report affected components and Features.

stack_policy_check

Check a proposed dependency or stack change against derived PolicyRules.

get_context

Return bounded stack, conventions, policies, and health context for an agent.

propose_context_update

Create a reviewable context proposal without writing to the repository.

Reference

REST API

The versioned API is the contract used by Instrument. Send a per-organization `cf_` bearer token and, where relevant, a `repo` query parameter.

Authentication
Authorization: Bearer cf_<token>
X-Conformative-Api: v1
GET /api/v1/features

Feature intent and accepted implementation links.

GET /api/v1/drift

Organization-scoped drift feed.

GET /api/v1/blast-radius

Evidence-backed impact analysis.

GET /api/v1/health

Conservative project-health contract.

GET|POST /api/v1/approvalsPro

Approval queue and decisions.

GET /api/v1/storyPro

Windowed project storyline.

Cacheable reads return an ETag and honor If-None-Match. Authentication failures return 401; cross-organization repositories are indistinguishable from missing repositories; unavailable entitlements return 403 with an upgrade hint.

Reference

Configuration

Most users can start with no configuration. These are the main controls used when operating or extending the platform.

.conformative.yml

Repository policy for Gatekeeper mode and severity threshold, feature issue label, and issue lifecycle behavior.

gate: report
severityThreshold: medium
featureLabel: feature
Semantic analysis

Local source and packaged runtimes can use their own `ANTHROPIC_API_KEY`; managed hosted semantic analysis requires Pro. `LLM_DISABLED` and `LLM_MAX_CALLS` provide controls. Raw files are not sent by default.

Local runtime

`CONFORMATIVE_HOME` changes local state; `CONFORMATIVE_COCKPIT_PORT` changes the preferred port; `CONFORMATIVE_SWEEP_MINUTES=0` disables sweeps.

Hosted mode

`CONFORMATIVE_MODE=hosted` enables fail-closed membership and managed-service gates. Auth, GitHub App, billing, and private service tokens are operator configuration.

Trust

Security, privacy, and accessibility

Conformative makes uncertain evidence visible, keeps tenant boundaries explicit, and minimizes the authority granted to automation.

Least code egress

Semantic steps receive minimal derived summaries rather than whole source files by default.

Human-approved writes

Scans and approvals do not imply a merge. A confirming repository observation establishes resolution.

Tenant isolation

Membership, project queries, REST tokens, and remote MCP sessions are organization-confined.

Credential discipline

MCP and invitation tokens are hashed at rest and plaintext is shown only once.

Fail-closed hosting

Missing hosted auth, membership, billing, or private service configuration never grants elevated access.

Accessible evidence

Core pages are server-rendered, keyboard operable, color-independent, reduced-motion aware, and covered by axe.

Help

Troubleshooting

Start with the evidence Conformative already records. Avoid treating a missing result as a clean result.

Local Cockpit does not open

From a source checkout, run `pnpm --filter @conformative/cli conformative doctor`. After the npm release, run `conformative doctor` through the verified package. Check daemon and Cockpit liveness, then inspect the reported log path.

Project stays partial or unverified

Open Overview and inspect coverage. Confirm intent, link uncovered Features, and rerun a successful full scan.

Semantic findings do not update

Verify the API key and controls. A disabled, exhausted, or malformed semantic pass cannot resolve earlier semantic evidence.

Agent cannot see the MCP server

Run `doctor`, then re-run `add <path>`. Conformative preserves existing tool configuration and reports manual wiring when needed.

Hosted repository is stale

Refresh GitHub access, verify the installation and repository identity, then retry the exact-head scan from onboarding.

Ready to build the first map?

Return to the quickstart or open the Cockpit.

QuickstartOpen Cockpit