Devora

简体中文

Devora is the project context and engineering control plane for AI coding agents.

Coding agents can read code, but they cannot reliably infer every business boundary, engineering rule, system relationship, or historical decision. That missing context leads to repeated explanations, inconsistent implementations, and unsafe changes.

Devora closes that gap across the development lifecycle:

• Before development, it turns code, documents, and human clarification into durable, agent-readable project context.
• During development, it applies reusable project Skills and keeps each requirement inside an explicit Change boundary.
• Before release, it uses technical and business risk to select quality gates and retain reviewable evidence.

Devora sits on top of Codex, Claude Code, OpenCode, Cursor, or another coding agent. It does not replace the agent, run a separate model, or automatically rewrite problems it discovers.

Start in three minutes

Devora requires Python 3.11 or later. Install it with uv:

uv tool install devora-cli
cd /path/to/project
devora init . --integration codex --language en

Then open your coding agent and run the generated Devora entry point:

$devora

Understand this project first, then help me implement order cancellation.
The PRD and UI references are in ./requirements/order-cancel/.

Use /devora instead of $devora with Claude Code, OpenCode, Cursor, and generic slash-command integrations.

That is the normal workflow. You do not need to operate every Devora CLI command yourself; the connected agent uses the deterministic commands when it needs them.

What happens after import?

Initialize
    ↓
Understand and clarify the project
    ↓
Reuse or build project Skills
    ↓
Develop through a controlled Change
    ↓
Validate, Review, and hand off
    ↓
Feed durable conclusions back into project context

1. Initialize — Devora creates a small .devora/ workspace and an adapter for your coding agent.
2. Understand — the agent reads bounded code and available documents, then asks only about material unknowns. Governance is clarification, not an instruction to rewrite legacy code.
3. Build capabilities — the agent reuses reviewed Skills when possible and creates project-specific Skills only when necessary.
4. Develop — a Change records the requirement, approved scope, risks, tasks, and evidence. Simple work stays simple; complex work expands only when needed.
5. Validate — Devora selects quality gates from the actual risk and project capabilities. “Tests passed” and “safe to release” are separate decisions.
6. Learn — confirmed decisions, rules, risks, and reusable workflows return to project context and Skills instead of disappearing in chat history.

The three concepts to know

They are connected: Governance defines what is true and allowed; Skills encode how recurring work should be done; each Change applies both to a specific task and returns durable lessons afterward.

What Devora creates

Initialization keeps the repository structure intentionally small:

.devora/
├── project.md              # Entry point and current project understanding
├── context/                # Durable project knowledge
│   ├── product.md
│   ├── engineering.md
│   ├── architecture.md
│   ├── rules.md
│   ├── risks.md
│   └── decisions.md
├── skills/                 # Project-specific Skills
├── changes/                # Current work and compact history
│   └── history/
└── state.json              # Machine-readable workflow state

Devora does not create separate roles/, custom/, project-local scripts/, or integrations/ directories. Human-readable knowledge stays in Markdown; workflow state stays in state.json.

A routine Change may contain only one file:

.devora/changes/order-copy-fix/
└── change.md

A complex or cross-repository Change can add tasks.md, review.md, evidence/, or handoff/ on demand. Completed Changes are compacted into changes/history/; they do not remain active or grow into an endless nested tree.

Common ways to use it

Start with an existing project

$devora

Govern this project first. Focus on architecture, engineering conventions,
business-critical operations, and anything that cannot be confirmed from code.

The scan is read-only. Risk hints become questions and evidence to clarify, not automatic refactoring tasks.

Implement a requirement from several sources

$devora

Implement the refund flow. Use the PRD URL, ./design/refund.png,
and ./openapi/refund.yaml as requirement sources. Clarify conflicts before coding.

Devora can track conversations, local files or directories, URLs, UI images, tickets, and API material in one requirement baseline. Material conflicts and source drift block development until they are resolved or explicitly accepted.

Validate without changing product code

$devora

Run a release validation only. Do not modify business code.
Check the API contract, dependency vulnerabilities, and regression suite.

The agent uses a validation-only Change, so findings still receive explicit Review without silently expanding into remediation.

Refresh project knowledge

$devora

The payment approval process changed. Update the relevant project context
and Skills, but do not implement a product change.

The agent uses a governance-only Change and updates only the affected scopes.

Safety and quality model

Devora controls both kinds of risk:

• Technical risk — database mutation, permissions, infrastructure, compatibility, concurrency, production operations, and recovery.
• Business risk — payments and assets, privacy, pricing, inventory, user rights, compliance, approval, and bulk operations.

For every Change, 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.

Quality gates are risk-driven. A passed unit suite does not override a missing security check, unresolved business rule, stale contract, or required approval. Devora retains the reason and evidence behind the final Review/Handoff decision.

Supported coding agents

Switch or refresh an integration without rebuilding project knowledge:

devora integrations
devora integration use claude .
devora integration upgrade .

Useful CLI commands

Most users can stay inside $devora or /devora. These commands are useful for inspection, automation, and debugging:

devora status --json                 # Current project and Change state
devora doctor . --json               # Read-only health check
devora govern scan --json            # Read-only project evidence inventory
devora govern status --json          # Governance readiness
devora skill list --json             # Project Skill status
devora quality scan --json           # Discover test and security capabilities
devora quality status --json         # Quality baseline status
devora quality gate --json           # Release-readiness decision
devora change audit --json           # Verify authorized file scope
devora state restore .               # Recover the previous valid state

Use devora COMMAND --help for the complete deterministic interface.

Frequently asked questions

Will Governance modify my code?

No. Governance starts with a bounded read-only inventory and asks for clarification when evidence is incomplete. A discovered problem does not authorize Devora to refactor it.

Must the project be well documented first?

No. Existing PRDs, wikis, AGENTS.md, architecture notes, and team experience are useful sources, but Devora is designed to build context progressively through evidence and clarification.

Does every task create many files?

No. A routine Change starts with only change.md. Additional artifacts appear only for complex, high-risk, approval-sensitive, or cross-repository work.

Does Devora replace tests or security tools?

No. It discovers and coordinates the tools already suitable for the project, records their evidence, and prevents missing required checks from being mistaken for a releasable result.

Where does old Change information go?

Completed Changes are compacted into history. Reusable conclusions move into context/ or skills/, keeping active workspaces small.

Documentation

• Architecture
• GA validation report
• State JSON Schema
• Development plan
• Changelog

Devora 2.0 is the current stable release. It supports Python 3.11–3.14 and is validated on Linux, macOS, and Windows.

License

Devora is licensed under the Apache License 2.0.