A / THE IMPLEMENTATION VIOLATES THE TARGET
Fix the implementation.
Keep the accepted contract. Remove the forbidden crossing or restore the declared interface, then run the checks again.
VISION & ROADMAP
Architecture-first
Agentic Engineering
AI agents are changing how we write software. ArchKeel is changing how we design, control and evolve its architecture.
AI can write code. Architecture shouldn’t be an accident.
Deterministic foundation available. Collaborative Studio planned.
Design together. Build within boundaries. Challenge decisions. Evolve consciously.
01 / PLANNED
ArchKeel Studio.
A shared workspace for the human architect and a frontier AI agent: design on a whiteboard, discuss alternatives in chat, and review the resulting Target change before accepting it.
Interactive concept · planned
Explore the views, select a component or open the proposed change. Illustrative data; no live agent or contract changes.
BOOKING / ACCEPTED BOUNDARY
Undeclared API → store crossing
Booking domainOwn booking decisions. Keep persistence and delivery behind declared interfaces.
Accepted Proposed
Concept view · illustrative data.
Start with purpose
Capture requirements, constraints and the decisions that need human judgment.
Work directly on the canvas
Move and connect components; inspect responsibilities and interface boundaries.
Discuss alternatives
Ask an AI architect to explain trade-offs and propose a concrete change.
Refine where it matters
Drill into modules, interfaces and classes as the design needs detail.
02 / A REVIEWED FEEDBACK LOOP
Architecture can change.
Make the decision visible.
A coding agent can discover a valid reason to change the design. The development loop should return that finding to the architect with evidence, alternatives and consequences.
Select a checkpoint or return path to inspect its responsibility.
Human + AI architect
Design & review
Define purpose, components, responsibilities and interfaces. Record assumptions that still need evidence. Inspect the proposed boundaries and alternatives. Check whether the Target expresses the intended system.
B / THE ARCHITECTURE NEEDS TO CHANGE
Review an amendment.
Propose an exact policy change with rationale and impact. The architect decides; an accepted amendment establishes the next Target.
This is the intended end-to-end workflow. CLI validation and amendments exist today; Studio’s collaborative authoring and review interface are planned.
03 / INTENT BEFORE IMPLEMENTATION
Why architecture-first?
A coding agent works toward the task in front of it. Across many changes, locally reasonable choices can accumulate into a system nobody deliberately designed. Behavior tests may still pass while ownership and dependency boundaries erode.
Architecture-first engineering makes those decisions explicit and progressively refines them. ArchKeel turns supported parts of that intent into executable constraints. Your harness or CI runs the checks and decides whether a change may proceed.
| Approach | Where architecture comes from | What needs deliberate review |
|---|---|---|
| Vibe coding | Architecture emerges while prompts and implementation evolve. | The resulting structure and the assumptions carried into it. |
| Architecture-first engineering | People and agents design responsibilities and boundaries, then refine them as they learn. | Trade-offs, ownership and proposed changes to the Target. |
| ArchKeel’s contribution | A versioned contract makes supported architecture rules checkable against code. | Violations, missing evidence and exact changes to accepted policy. |
04 / AVAILABLE TODAY
A foundation you can inspect.
ArchKeel is an open-source tool for deterministic architecture validation. It checks static code against an independently declared Target and produces evidence for people, coding agents and CI.
Verified against release 1.1.1 and current Main on 10 October 2026. Release 1.1.1 · Main source reviewed
Executable architecture contracts
Declare components, responsibilities, interfaces and permitted dependencies in a versioned contract. Intent stays reviewable as the implementation changes.
Contract and rule referenceDeterministic architecture validation
Run local checks without an LLM. Forbidden imports, misplaced types and other supported violations become repeatable findings within the documented runtime and analysis scope.
Validation and command scopeAs-Is / Target / Diff
Explore observed code, declared intent and their differences in one report. These are views of one snapshot, so a diagram does not silently become permission.
Explore the real demosNested architecture and UML
Drill into nested components, modules and supported class, interface, member and relationship declarations. Unsupported or incomplete evidence stays visible.
UML demos and coveragePython, TypeScript and Dart
Analyze all three through the Python installation. TypeScript provides lexical UML and bounded static relationships; Dart needs no SDK for analysis. Language profiles have different limits.
Language profiles and limitsReports for agents and CI
Retrieve a compact architecture summary, scoped findings and source evidence. Codex/Claude skills and CLI gates connect the results to your existing development workflow.
Agent setup and integrationControlled architecture amendments
Compare policy against a reviewed base. Permission widening requires an explicit amendment bound to the exact policy pair. Approval authority and protected CI remain responsibilities of your workflow.
Target-first amendment workflowPASS / FAIL / UNKNOWN evidence
Distinguish supported conformance, decided violations and missing evidence. Filters keep global verdicts visible; a successful report command alone is not an all-clear.
Read the verdictsReal Explorer views. Declared intent at two levels.
Original repository screenshots from 1.1.1. Open either view to inspect the published interactive demo. These source projects retain documented analysis gaps.
Architecture validation complements runtime tests. It does not prove runtime behavior, design quality or complete language semantics. A recorded architect name is provenance, not authenticated approval.
05 / PRODUCT ROADMAP
Build on evidence.
Expand the way we design.
The sequence describes product direction. Planned stages carry no release-date promise. Existing UML and amendment mechanisms provide a foundation for the new authoring experience.
- 01
TODAY
AvailableFoundation
Executable contracts, deterministic checks, As-Is / Target / Diff and scoped evidence.
Release 1.1.1 - 02
NEXT
PlannedInteractive authoring
Typed Target proposals, direct canvas editing, semantic previews and explicit approval.
Read the Studio concept - 03
THEN
PlannedAI collaboration
Chat and whiteboard on one contract, an AI architecture assistant and a reviewed path for architecture challenges.
Inspect the development loop - 04
TARGET
Long-term VisionArchitecture-first Agentic Engineering
Progressive design from components to interfaces and classes, continuous validation and controlled architecture evolution.
Related Target work · #340
Related foundation work: inner Target coverage (#340) and UML demo/browser acceptance (#339). These issues track existing analysis and reporting work; they are not Studio delivery commitments. #340 · #339 · GitHub Roadmap
06 / HOW WE WANT TO BUILD
Human control stays explicit.
Human judgment. AI acceleration.
Agents explore and implement options. People decide which trade-offs the system should carry.
Architecture is a decision, not an accident.
Record responsibilities and boundaries before relying on them. Refine the design as evidence changes.
Agents may propose. Architects decide.
A proposed improvement needs a visible review and a responsible decision before it changes the Target.
Trust requires evidence.
Attach claims to the checked source, rules and results. Keep uncertainty visible.
Questions about the vision
Is ArchKeel Studio available today?
No. The whiteboard and conversational architecture assistant shown here are a planned experience. Release 1.1.1 provides the CLI, architecture contracts, validation and Explorer reports.
Can an AI agent change the architecture?
Agents can propose boundaries and amendments. The workflow must control who accepts policy changes and protect the contract and gates. ArchKeel checks the declared rules; it is not an agent sandbox.
Does architecture-first require a complete design before coding?
No. Start with the boundaries that matter and progressively refine modules, interfaces and classes. Incomplete intent and missing static evidence must remain visible.
How does ArchKeel help prevent architectural drift?
ArchKeel compares code with the declared contract and can reject unamended permission widening against a reviewed base. Required CI gates make those findings actionable; behavior tests and human review cover different questions.
ARCHKEEL / OPEN SOURCE
Start building with architectural intent.
Use the foundation today. Help shape the next authoring experience.