Engineer Playbook
How rkito connects to your workflow, reads your code, and governs your AI coding agents.
How rkito connects to your workflow
The CDA (Continuous Design Audit) pipeline runs as a required PR status check: rkito/cda. On every PR open and push, rkito evaluates all active Lenses against the PR diff.
rkito connects via webhook to your GitHub or GitLab repository. Navigate to /settings/repositories to connect a repo. See Getting Started for full setup instructions.
Reading a BLOCKED PR
A BLOCKED status means a Lens found a structural violation in your PR. The CDA output shows which Lens triggered, what the specific violation is, and what architectural rule it references.
- The architect reviews and approves a Change Intention (CHI) — this signals a legitimate structural change was intended and approved.
- You rework the code so it no longer violates the Lens — no CHI needed.
Navigate to /changecontrols/changeintentions to see the auto-drafted CHI for your blocked PR.
Starting a new feature — explore, describe, import
Before you write code or raise a CHI, rkito gives you three ways to get oriented — and to start the design conversation with your architect from a position of context, not guesswork.
01 Explore the Architecture Ledger
Before touching a domain, navigate to the Architecture Ledger to see the current state of the system — what Systems, Components, Interfaces, and Behaviours already exist, what boundaries are defined, and what CHIs are currently active on the entities your feature will touch.
- Find the Systems and Components your feature will touch. Read their current approved state — interfaces, boundaries, active CHI scope.
- Check whether any active CHIs already claim scope over the entities you plan to modify. If so, coordinate with that engineer or agent before raising your own.
- Browse the Skills bound to the entities you’ll work with — they tell you the approved interaction patterns, what’s permitted, and what Lenses will evaluate your PR.
Know what you’re changing before you change it. The Ledger is the ground truth of the current design state.
02 Describe your intent to rkito
When creating a new CHI, describe what you intend to do in plain language. rkito analyses your description against the Architecture Ledger, suggests which entities are affected, what Lenses apply, and what the scope of the structural change looks like. The architect refines and approves — but your natural language intent becomes the starting point.
“I have a new subscriber domain subscribing to the event pipeline.”
rkito identifies the Event Pipeline system, the subscription interface, the relevant Pillar covering event-driven boundaries, and the Lenses that will evaluate subscriber patterns.
“We need to add a new external payment provider alongside the existing one.”
rkito surfaces the Payment Service entity, active integration patterns in Steering, the Security Pillar Lenses on external integrations, and any existing CHI scope on the payment domain.
“I want to split the Order Service into Order Command and Order Query services.”
rkito maps this to the Order Service Ledger entity, flags the interface contracts that will need to change, and identifies any downstream components with dependencies on the current single-service model.
03 Import from Jira or Lucid Charts
If you have already ideated in Lucid Charts or captured the feature as a Jira user story, rkito can import that as the basis for a CHI — skipping the blank-page problem entirely.
Navigate to /changecontrols/changeintentions → New → Import → Jira. rkito reads the user story description and acceptance criteria, maps them to Architecture Ledger entities, and creates a draft CHI. The architect reviews the mapping, adjusts scope if needed, and approves.
Navigate to /changecontrols/changeintentions → New → Import → Lucid. rkito parses the diagram, identifies new components, changed interfaces, and modified relationships, and creates a draft CHI with those structural changes declared. The imported diagram becomes the architectural evidence in the CHI record.
Raising a CHI before structural changes — the right sequence
Structural changes include: new service, new interface, changes to component boundaries, new dependency on another domain, changes to data contracts. Raise a CHI before you write the code — not after the PR is BLOCKED.
- Navigate to
/changecontrols/changeintentions→ New CHI → describe the structural change you intend to make. - Wait for the architect to approve the CHI.
- Write the code and open the PR — the structural review check will pass.
This is what drives the IFR metric — the Intent-First Rate. CHI first → code second → PR passes → no blocked PRs.
Reading Steering artefacts before you code
Before touching a domain’s code, read its Lenses and Prompts in Steering. These define exactly what the CDA pipeline will evaluate your PR against.
Using AI coding agents with rkito MCP
If you use Claude Code, Cursor, Cline, Copilot Workspace, or any MCP-compatible agent, rkito provides an MCP (Model Context Protocol) server that loads your organisation’s design context into the agent before it writes code.
- Active Lenses for the domains being modified
- Pillar definitions
- Architecture Ledger entries for referenced components
- Active CHIs
Agents generate structurally sound code that violates your organisation’s specific architectural intent → the ADRIFT metric rises.
Add the rkito MCP server to your agent configuration. Navigate to /settings/mcp for the connection URL and auth token. For Claude Code, install the A2D plugin from the rkito marketplace instead; Copilot, Cursor, VS Code and CLI set-ups are coming soon.
The MCPCAR metric tracks what percentage of your agent PRs loaded design context before generating code.
Using rkito from the CLI
The rkito CLI is available for local pre-commit checks before pushing. Run a local audit to surface Lens violations during development — the same evaluation the CDA pipeline runs on PR open — before the PR is open.
- Install:
npm install -g @rkito/cli - Run
rkito audit --localto evaluate your working tree against active Lenses. - Output shows: Lens name, violation description, what to change. Fix violations before committing.
Navigate to /settings/cli for your org’s CLI auth token.