Devora

English | 简体中文

Devora builds durable project context for AI coding agents and applies lightweight controls to development changes and risk. It works with the coding agent you already use, without introducing a separate model runtime or requiring a large document set for every routine task.

Core model

• Governance — progressively capture product, engineering, architecture, rule, risk, and decision context from code, documents, and human clarification.
• Capability building — discover and reuse reviewed Skills first, then create only the missing project-specific workflows in .devora/skills/; the agent selects them by task instead of relying on fixed frontend/backend roles.
• Development — silently create a minimal Change for real development work; ordinary work gets only change.md, while complex work adds artifacts on demand.
• Quality assurance — discover project test capabilities, generate a risk/type-specific validation matrix, and retain independently reviewable release evidence without silently expanding remediation scope.

Quick start

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 describe the task to your coding agent and use the main entry point:

$devora

Implement order cancellation. The reference material is in ./requirements/order-cancel/.

Use /devora with slash-command integrations.

Project files

Initialization keeps the project structure small:

.devora/
├── project.md
├── context/
│   ├── product.md
│   ├── engineering.md
│   ├── architecture.md
│   ├── rules.md
│   ├── risks.md
│   └── decisions.md
├── skills/
├── changes/
│   └── history/
└── state.json

• project.md is the project entry point and current understanding.
• context/ contains durable, agent-readable project knowledge that evolves through governance and development.
• skills/ contains project-specific agent Skills.
• changes/ contains the active task workspace and compacted history.
• state.json contains machine-readable workflow, dependency, policy, and freshness state; human-readable project knowledge remains in Markdown.

Devora no longer creates roles/, custom/, project-local scripts/, or a separate integrations/ directory. Rules and capabilities live directly in the relevant context and skill locations.

Project Skills use the standard <name>/SKILL.md structure. The agent first searches installed Skills, approved catalogs, and suitable upstream repositories. A reused Skill is reviewed locally and pinned to a source revision; if none fits, the agent uses a standard Skill creator or the minimal skill create command. Validation records Governance scopes, Findings, Controls, mandatory organization rules, and observable scenarios. A Skill remains pending until every declared scenario passes, and becomes stale when its package or Governance dependencies change:

devora skill list --json
devora skill install /tmp/reviewed-release-check \
  --source https://example.com/skills/release-check \
  --revision abc123 --json
devora skill create order-change \
  --description "Change governed order behavior." \
  --instructions "Preserve confirmed state and payment controls."
devora skill validate order-change --scope orders \
  --finding orders/cancel-rule \
  --scenario "cancel-unshipped=Cancel only an unshipped order." --json
devora skill scenario order-change cancel-unshipped \
  --result passed --evidence "Scenario test passed." --json

Network discovery and review remain Agent operations. The CLI deliberately installs a local, already reviewed package instead of executing an arbitrary remote Skill directly.

How Changes work

The agent directly decides whether a request continues the current Change or starts a new one. This does not require a separate classifier and normally does not require a user choice.

A routine low-risk task starts with only:

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

Complex, high-risk, or approval-sensitive work can use an owning module and expand on demand:

.devora/changes/payments/payment-refund/
├── change.md
├── tasks.md       # optional
├── review.md      # optional
├── evidence/      # optional
└── handoff/       # cross-repository work only

On completion, Devora compacts a flat Change into .devora/changes/history/, or a module-scoped Change into .devora/changes/history/<module>/. A Change has one owning module; other affected modules are recorded in change.md instead of creating nested or duplicated workspaces. Durable conclusions belong in context/ or skills/, rather than accumulating indefinitely in active workspaces.

Advanced users and agents can call the deterministic CLI directly:

devora status --json
devora change start order-cancel --json
devora change start release-audit --profile validation-only \
  --exclude src --type security --json
devora change start payment-refund --module payments --scope payments \
  --skill payment-change --allow services/payments \
  --exclude services/auth --type api --type database --json
devora change ensure --tasks --evidence --json
devora change setup design --json
devora change complete design --json
devora change expand --reason "Refund behavior was added" \
  --scope refunds --allow services/refunds --json
devora change audit --json
devora change validate refund-boundary --result passed \
  --execution automatic --target services/payments/refund.py \
  --evidence "Boundary tests passed." --json
devora quality gate --json
devora change close --result completed --json

Every Change has one standard profile. implementation is the default and permits only authorized business-file mutations. validation-only runs the project quality matrix without permitting business-file changes. governance-only records governance work without inventing implementation checks. The two read-only profiles always use the tracked workflow so their findings receive an explicit Review.

Design, Build, and Review are an optional controlled workflow for ordinary implementation work, and the standard path for read-only profiles. Completing Build means the planned work or validation execution finished; it does not mean the release gate passed. Failed or blocked validation can proceed to Review as changes_required or blocked, but can never be approved. When authorized scope or risk grows during execution, change expand adds scopes, Skills, allowed/protected paths, and high-risk artifacts without replacing the original baseline.

Multi-source requirements

A real requirement may combine a conversation, local PRD, directory, URL, UI image or design, ticket, and API material. The connected Agent reads those inputs; Devora records only material source provenance and the unified baseline in the existing Change—no additional project directory is created. Trivial prompt-only work keeps the default not_required baseline.

devora change source record refund-prd --kind url \
  --location https://example.com/prd/refund --status read \
  --revision v3 --summary "Refunds are allowed for 30 minutes" --json
devora change source record refund-ui --kind image \
  --location requirements/refund.png --status read \
  --summary "The UI exposes refund from order details" --json
devora change requirement clarify refund-window --kind conflict \
  --source refund-prd --source refund-ui \
  --summary "The sources imply different refund windows" \
  --impact "This changes asset movement and button availability" --json
devora change requirement resolve refund-window \
  --resolution "Use the PRD 30-minute limit" --actor product-owner --json
devora change requirement confirm \
  --summary "Paid orders may be refunded for 30 minutes" \
  --acceptance "The API rejects refunds after 30 minutes" \
  --actor product-owner --json

Local files and directories are fingerprinted automatically. Remote material can retain an observed revision and SHA-256 snapshot digest. Pending, inaccessible without an explicitly accepted limitation, materially unresolved, or locally drifted sources block Design completion, Build entry, and release. Updating a confirmed material source invalidates dependent stages and validation evidence so the Agent must reconcile and reconfirm the requirement. A versioned contract source is the bounded exception: once its producer and consumers confirm it and Build starts, Devora recognizes its authorized implementation change instead of deadlocking the Change; drift before Build remains blocking.

Quality control

Quality remains a control plane over the existing project, Skill, and Change model; it does not create another .devora directory tree. A bounded read-only scan records declared capabilities such as pytest/Jest/Vitest, Storybook, Playwright/Cypress, visual and accessibility tooling, OpenAPI/Pact, database migrations, dependency scanning, SAST/DAST, and infrastructure planning:

devora quality scan --json
devora quality status --json

Each Change can select repeatable policy types including frontend, api, database, authorization, security, dependency, infrastructure, and cross-repository. Devora merges those policies with Governance validation IDs and L1-L4 risk requirements. Security Changes, dependency Changes, and L3/L4 Changes with a discovered dependency-audit capability require dependency-vulnerability-audit. Missing environments remain blocked or not_run; high-risk work cannot become release-ready merely because its unit suite passed.

not_applicable is a distinct, evidence-required result for irrelevant policy checks. Risk-, Control-, or detected dependency-required gates cannot use it as a bypass. Validation --target values describe read-only coverage and therefore may point at protected source; actual mutations remain governed by the independent scope audit. Evidence retained inside .devora must use report or snapshot extensions such as .json, .snapshot, .log, or .txt, preventing host lint/build tools from discovering temporary source files.

Validation evidence distinguishes automatic, manual, and external execution and can retain the provider, checked code path, linked Governance risk and Control, and a local report or external URL:

devora change validate static-security-analysis --result passed \
  --execution external --provider codeql \
  --target services/auth/policy.py \
  --risk authorization/admin-boundary \
  --control authorization/deny-fixture \
  --artifact reports/codeql.sarif \
  --evidence "No high-severity findings in the authorized scope." --json

For a local automatic check, quality run executes one command without a shell, applies a timeout, records the exit status, and retains the complete combined output under the active Change's evidence/executions/ directory:

devora quality run unit-regression \
  --command "python -m pytest tests/payments -q" \
  --timeout 600 --provider pytest --environment devcontainer \
  --target services/payments --fail-on-result --json

A command that cannot start or exceeds its timeout is recorded as blocked. Other non-zero exits default to failed; use --nonzero-result blocked only when project evidence establishes that the failure is environmental. The command runner does not use a shell, does not infer success from output text, and does not turn capability or environment readiness into test evidence.

devora quality gate refreshes the actual file-scope audit and writes JSON plus Markdown release-readiness summaries into the Change's existing evidence/ directory. The gate distinguishes pending work, blockers, explicit approval, and ready state.

Risk governance

Devora distinguishes:

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

When evidence is insufficient, the agent asks only about unknowns that materially change behavior or controls. A legacy code issue does not itself authorize broad refactoring, and confirmed exceptions may remain part of project context.

Governance begins with a bounded read-only inventory. It detects languages, manifests, commands, entry points, five context-source candidate groups, module candidates, and path-based technical or business risk hints while excluding Devora-owned files and common dependency/build directories. These candidates route Agent inspection; they are never promoted to facts or module boundaries automatically.

The Agent records evidence-grounded Findings, their conflict/dependency/supersession relations, L1-L4 risk, required Controls, and validation IDs. Multi-round clarification stays inside bounded scopes; confirmed conclusions are rendered into protected context blocks without replacing team content. Project/module/focused profiles define coverage. Unresolved relations or high risks without Controls block completion; unavailable or explicitly unknown controls produce limited. Governance also compares its starting snapshot before completion, so a read-only governance session cannot silently absorb business-code edits. A Change can require completed scopes; reopening one blocks development and makes dependent Skills stale.

devora govern scan --json
devora govern status --json
devora govern start order-refund --profile focused --json
devora govern observe order-refund refund-threshold \
  --category business_risk \
  --statement "The refund threshold is not represented in code." \
  --evidence src/payments/refund.py --target risks \
  --risk-level L4 --validation refund-boundary --json
devora govern record order-refund refund-threshold \
  --category business_risk \
  --finding refund-threshold \
  --observation "No confirmed refund threshold exists in code." \
  --question "Which amount requires manual approval?" \
  --impact "A wrong threshold can release assets without approval."
devora govern resolve order-refund refund-threshold \
  --outcome rule --answer "Refunds at or above 500 CNY require approval."
devora govern control order-refund manual-approval \
  --finding refund-threshold --kind approve \
  --statement "Refunds at or above 500 CNY require Finance approval." --mandatory
devora govern complete order-refund --json

Continuous governance and enterprise policy

Completed Governance scopes seal local evidence fingerprints. devora govern drift later reports whether supporting code, configuration, or documentation changed; affected scopes block their Changes and dependent Skills become stale until the conclusion is re-governed. Quality capability structure is checked separately from ordinary source-file churn.

Company defaults and mandatory policies live in structured state and are rendered into a protected block in the existing context/rules.md, preserving team notes. A Change freezes the applicable policy revisions and scoped, approved exceptions at start; later rule or expiry changes become visible release blockers. A project-local, reviewed JSON file can act as a versioned shared source:

devora govern drift --json
devora govern policy payment-approval \
  --statement "Asset movement requires Finance approval." \
  --enforcement mandatory --scope module:payments \
  --validation finance-approval --risk-level L4 --no-exceptions --json
devora govern policy-sync company-baseline --file config/devora-policies.json --json
devora govern exception legacy-window --policy compatibility-default \
  --scope path:services/legacy --reason "Migration window" \
  --approver platform-owner --expires-at 2026-12-31T23:59:59+08:00 --json
devora change policy-refresh --reason "Adopt the approved policy revision" --json

Cross-repository work uses the existing optional handoff only. Register repositories, then record a versioned producer/consumer contract in the active Change; a cross-repository Change cannot release while its contract is missing or merely proposed. Incident and Review feedback can reopen only named Governance scopes and stale only named Skills. devora govern coverage summarizes freshness across Governance, Skills, quality capabilities, policies, exceptions, contracts, and open feedback.

devora govern repository orders-api --location ../orders --role producer --json
devora govern repository checkout-web --location ../checkout --role consumer --json
devora change contract order-created --producer orders-api \
  --consumer checkout-web --kind event --version 2.0.0 \
  --source contracts/order-created.json --json
devora change contract-status order-created --status confirmed \
  --evidence "Producer and consumer approved v2" --actor platform-review --json
devora govern feedback refund-incident --kind incident --severity L4 \
  --summary "Refund approval was bypassed." --evidence INC-42 \
  --scope payments --skill payment-change \
  --action "Re-govern the approval boundary." --json
devora govern coverage --json

Project health and pilot acceptance

devora doctor performs a bounded, read-only health check. The standard profile reports daily attention items without changing Governance state. The pilot profile is intentionally stricter: it requires current Governance, a complete quality baseline, active project Skills, clean lifecycle state, no unfinished Change, intact Agent adapters, and at least one completed representative Change.

devora doctor . --json
devora doctor . --profile pilot --report reports/devora-pilot.md --json
devora doctor . --profile pilot --fail-on-issues --json

Lifecycle state is closed explicitly rather than overwritten or deleted:

devora govern policy-status review-default --status retired \
  --reason "Moved to the company baseline" --actor platform-owner --json
devora govern exception-revoke legacy-window \
  --reason "Migration completed" --actor platform-owner --json
devora govern feedback-status refund-incident --status addressed \
  --evidence "Remediation review accepted" --actor incident-owner --json
devora change contract-status order-created --status confirmed \
  --evidence "Producer and consumer approved v2" --actor platform-review --json

These commands primarily give the agent deterministic state operations. Normal use still requires only $devora.

Supported integrations

devora integrations
devora integration use claude .
devora integration upgrade .
devora integration uninstall claude .

Development

uv sync --extra test
uv run pytest
uvx ruff format --check src tests scripts/ci
uvx ruff check src tests scripts/ci

Additional documentation:

• v2 architecture
• v2 development plan
• v2 state JSON Schema
• M4 Alpha validation map
• M5 Beta validation map
• M6 RC validation map
• RC2 hardening validation map
• RC3 multi-source requirement validation map
• Changelog

Devora is currently release-candidate software. The v2 enterprise-governance experience will continue to evolve.

License

Devora is licensed under the Apache License 2.0.