Devora: a context and control plane that sits on top of your coding agent

The gap Devora claims to fill: context an agent cannot read from code

The README opens with a narrow, testable complaint: coding agents can read code, but they cannot reliably infer every business boundary, engineering rule, system relationship, or historical decision. The stated consequence is repeated explanations, inconsistent implementations and unsafe changes. That is a specific failure mode rather than a general pitch about AI productivity, and it defines the audience. Devora is for teams that already run Codex, Claude Code, OpenCode, Cursor or a comparable agent against a codebase where the important constraints are not visible in the source tree. If your repository is a small library with no business rules, the problem Devora describes does not exist for you. The README is explicit that Devora sits on top of the coding agent, does not replace it, does not run a separate model, and does not automatically rewrite problems it discovers. That last clause is the honest one. Devora is a record-keeping and gating layer, not a fixer.

Governance, Skill and Change: the three objects the whole design hangs on

The README reduces the system to three concepts, and the table is worth reading literally. Governance makes project boundaries and unknowns explicit, and its typical contents are architecture, engineering rules, business constraints, risks and decisions. A Skill turns a repeatable project workflow into a reusable agent capability, described as steps, constraints, scenarios and validation evidence. A Change controls one piece of work from requirement to Review, carrying scope, source material, tasks, tests, approvals and handoff. The relationships matter more than the definitions. Governance defines what is true and allowed. Skills encode how recurring work should be done. Each Change applies both to a specific task, then returns durable lessons afterward. That is a closed loop, and it is the part that distinguishes Devora from a prompt template. It is also the part that creates the maintenance burden, because the loop only closes if someone writes the conclusions back into .devora/context/ rather than letting them die in a chat window.

What devora init actually writes to disk

The README gives the full workspace layout, and it is deliberately small. Running devora init creates a .devora/ directory containing project.md as the entry point, a context/ folder with product.md, engineering.md, architecture.md, rules.md, risks.md and decisions.md, plus skills/, changes/ with a history/ subfolder, and state.json for machine-readable workflow state. The README states that Devora does not create separate roles/, custom/, project-local scripts/ or integrations/ directories, and that human-readable knowledge stays in Markdown while workflow state stays in state.json. That split is a real design decision: the Markdown files are meant to be read and edited by people, and state.json is meant to be read by the tool. A routine Change can be a single change.md file. A complex or cross-repository Change can add tasks.md, review.md, evidence/ or handoff/ on demand. Completed Changes are compacted into changes/history/ rather than remaining active. The claim that they do not grow into an endless nested tree is a constraint on the implementation, and it is the kind of thing you would want to confirm against a real repository after several months of use, since the README describes intent rather than observed behaviour.

Installation and the first three commands

The README states a Python 3.11 or later requirement and recommends uv for installation. The sequence is three lines: uv tool install devora-cli, then cd into the project, then devora init . --integration codex --language en. The --integration flag selects the adapter for your coding agent, and --language sets the output language. After that you do not drive the CLI directly. You open your coding agent and invoke the generated entry point, which is $devora for Codex and /devora for Claude Code, OpenCode, Cursor and generic slash-command integrations. The README frames this as the normal workflow: the connected agent calls the deterministic Devora commands itself when it needs them. The example prompt is worth noting because it shows the intended division of labour. You tell the agent to understand the project first, then implement order cancellation, and you point it at ./requirements/order-cancel/ for the PRD and UI references. Devora supplies the structure; the agent does the reading and writing.

Requirement sources, drift and the validation-only Change

One of the more concrete mechanisms in the README is requirement tracking. Devora can hold conversations, local files or directories, URLs, UI images, tickets and API material in a single requirement baseline. The stated rule is that material conflicts and source drift block development until they are resolved or explicitly accepted. That is a hard gate rather than a warning, and it is the kind of behaviour that will either save a team from a misread ticket or annoy it when a stale URL halts work. The README also documents a validation-only Change, used when you want release validation without touching product code. The example prompt asks the agent to check the API contract, dependency vulnerabilities and regression suite while explicitly not modifying business code. The stated benefit is that findings still receive explicit Review without silently expanding into remediation. There is a governance-only variant for refreshing context and Skills after a process change, which likewise avoids a product change. These two modes are the most useful thing in the documentation, because they let you run Devora against a codebase you are not yet ready to modify.

Risk-driven quality gates and the limit of a passing test suite

Devora separates two categories of risk. Technical risk covers database mutation, permissions, infrastructure, compatibility, concurrency, production operations and recovery. Business risk covers payments and assets, privacy, pricing, inventory, user rights, compliance, approval and bulk operations. For each Change, the README says Devora can freeze the authorized paths and project policy revisions, track requirement sources and cross-repository contracts, discover existing test capabilities, record repeatable evidence, and audit whether the implementation escaped its approved scope. The quality gate rule is stated bluntly: a passed unit suite does not override a missing security check, unresolved business rule, stale contract or required approval. The README also draws a line between tests passing and being safe to release, calling them separate decisions. This is a defensible position, but it is worth being clear about what Devora is not doing here. It is not running the security check or resolving the business rule. It is refusing to let a green test run stand in for those things, and recording why the gate was or was not satisfied.

Where Devora is the wrong tool, and what it competes with

The clearest limitation is stated by the project itself. Devora does not automatically rewrite problems it discovers, so a team expecting the tool to clean up legacy code will be disappointed. The governance scan is described as read-only, and risk hints become questions and evidence to clarify rather than automatic refactoring tasks. That is a deliberate choice, and it means the human work of answering those questions does not go away. A second limitation is the audience. Devora assumes a coding agent is already in the loop and that the project has boundaries worth making explicit. For a throwaway script or a repository where the only reader is the author, the .devora/ tree is overhead with no payoff. The natural alternative is a plain AGENTS.md or CLAUDE.md file checked into the repository root, which most coding agents read automatically. The difference in approach is structural. A single instruction file is flat and always loaded, and it has no notion of scope, evidence, approval or history. Devora splits the same knowledge into governance, Skills and per-Change records, and adds gates that can block work. The trade is real: you get drift detection and an audit trail, and you pay for it with a directory tree that someone has to keep current.

Licence, upgrade surface and what to check before committing

Devora is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, but it also requires that you retain copyright and licence notices and state significant changes. That is a summary of the licence text, not legal advice, and if you plan to redistribute a modified Devora you should read the full terms. On maintenance, the release history in the supplied material shows v2.0.0 published on 2026-09-01, preceded by v2.0.0rc5 and v2.0.0rc4 the day before, and a last push to main on the same day as the final release. That is a concentrated release window rather than a long, steady cadence, and it is the only signal available here about how the project moves between versions. The upgrade cost itself is hard to assess from the README, because the workspace is Markdown plus state.json and the README does not describe a migration path between major versions. That is the specific thing to verify first: install devora-cli, run devora init . --integration <your agent> on a branch, and check whether the generated .devora/ files survive a version bump without manual repair. If they do not, the context you accumulate becomes a liability rather than an asset.

Editorial conclusion

Devora is aimed at teams already using a coding agent on a codebase with real business rules, where context currently lives in people's heads and chat history. It is the wrong tool for a solo script repository or anyone hoping the agent will infer boundaries on its own, since the README states plainly that Devora does not automatically rewrite problems it discovers. Before adopting, verify three things: that your Python is 3.11 or later, that an integration exists for your agent (the README names codex, Claude Code, OpenCode, Cursor and a generic slash-command path), and that you are willing to maintain .devora/context/ by hand, because nothing in the documentation suggests that content writes itself.

Official sources

1. cheney369/Devora on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases