Devora

English | 简体中文

Project-aware, spec-driven delivery workflows for coding agents.

Devora turns product intent into a traceable implementation and review flow. It installs a small set of commands, templates, and deterministic project-state scripts into your repository. Your coding agent still does the real work: reading the codebase, making technical decisions, implementing changes, and running validation.

Devora is designed for real feature delivery rather than one-shot prompting:

• requirements can come from product documents, designs, images, tickets, links, API descriptions, and conversation;
• the agent verifies relevant project context before defining the change;
• specifications, plans, test cases, and tasks remain linked;
• analysis findings are routed to the agent, the user, or an external owner;
• implementation and validation are tracked separately;
• an independent review and explicit human approval form the final pre-PR gate.

Devora is not a code index, RAG service, AST engine, coding-agent runtime, or multi-agent orchestrator. It defines the delivery process and delegates project work to the connected agent.

Quick start

Install the CLI from PyPI:

uv tool install devora-cli
devora --version

Initialize an existing repository:

cd /path/to/your-project
devora init . --integration codex

Start with project context when the repository is unfamiliar or complex:

$devora-project-context
$devora-specify Add an administrator action to disable a user

Then continue through the delivery flow:

$devora-clarify          # optional, only when product intent is ambiguous
$devora-plan
$devora-tasks
$devora-analyze
$devora-resolve          # only when analysis reports NOT_READY
$devora-implement
$devora-review

In Codex, Skills are invoked with $devora-*, not /devora-*. Other supported integrations use slash commands.

Supported coding agents

Codex is the default:

devora init .

You do not need to reinitialize the project to change coding agents. Switch the active integration while preserving shared Devora state and feature artifacts:

devora integration use opencode .
devora integration use cursor .

Unmodified files from the old integration are removed. User-modified files are preserved and reported.

How the workflow works

project-context (optional)
        ↓
constitution (initialize or revise project rules when needed)
        ↓
specify → clarify (optional)
        ↓
plan → tasks
        ↓
analyze → resolve (when needed)
        ↓
implement
        ↓
review → explicit human approval

Impact analysis is performed internally during specify; it is not an extra command. The later analyze stage has a different purpose: it checks whether the complete specification, plan, test cases, and tasks are safe and consistent enough to implement.

Product inputs and human control

specify can use any requirement sources the connected agent can actually access. Devora does not ship a duplicate document parser or browser. Instead, the agent inventories available sources and records them in intake.md with stable IDs, access status, conflicts, assumptions, and traceability.

summary.md is the human control surface. It keeps scope, decisions, risks, implementation progress, validation status, and the next action readable without requiring people to inspect every machine-oriented artifact.

When analysis finds a problem:

• AUTO_FIX: the agent repairs the workflow artifacts automatically;
• USER_DECISION: the agent presents plain-language options and a recommendation;
• EXTERNAL_BLOCKED: the exact external owner and action are recorded;
• ACCEPTED_RISK: the user must explicitly accept the risk.

Users are not asked to manually edit generated Devora documents.

Language and script backend

Artifact language defaults to auto. During specify, the feature locks to the dominant product-input language:

devora init . --language auto
devora init . --language zh-CN
devora init . --language en

Code identifiers, API names, exact contract strings, and source terminology are preserved in their original form.

Python is the default workflow-script backend and works across Windows, macOS, and Linux:

devora init . --script-type py

The Bash backend remains available for compatibility:

devora init . --script-type sh

The selected backend is recorded in .devora/init-options.json, and installed agent commands receive the correct script invocation automatically.

Upgrade and integration lifecycle

There are two upgrade steps:

1. Upgrade the global CLI package.
2. Upgrade the workflow files installed in each project.

uv tool upgrade devora-cli

cd /path/to/your-project
devora integration upgrade .

Devora uses separate ownership manifests:

.devora/integrations/
├── core.manifest.json
└── <integration>.manifest.json

During an upgrade, Devora:

• updates managed files that still match their previous hashes;
• removes obsolete managed files that were not modified;
• preserves and reports user-modified files;
• rejects unsafe, malformed, escaping, or symlinked manifest paths;
• never overwrites .devora/memory/constitution.md.

Use --force only when you intentionally want to replace customized managed files:

devora integration upgrade . --force

Manage integrations directly:

devora integration list
devora integration use cursor .
devora integration uninstall cursor .

Installed project structure

.devora/
├── init-options.json
├── feature.json                     # active feature pointer
├── integrations/
│   ├── core.manifest.json
│   └── <integration>.manifest.json
├── memory/
│   ├── constitution.md
│   └── project-context.md           # created by the optional command
├── scripts/
│   ├── python/                      # default cross-platform backend
│   └── bash/                        # compatibility backend
└── templates/

specs/
└── 001-feature-name/
    ├── intake.md
    ├── spec.md
    ├── summary.md
    ├── plan.md
    ├── test-cases.md
    ├── tasks.md
    ├── analysis.md
    ├── review.md
    └── optional design artifacts

A task checkbox means fully complete—not merely “code written.” Each task tracks implementation and validation independently, and can be checked only when its dependencies are complete and its declared evidence passes.

Existing projects and existing Devora installations

Running devora init in an existing application does not scan or rewrite business code. It installs the workflow files only.

To upgrade a project initialized by an earlier Devora version:

uv tool upgrade devora-cli
devora integration upgrade .

Legacy combined manifests are migrated into separate core and integration ownership. Existing feature artifacts and the project constitution are preserved.

Development

git clone https://github.com/cheney369/Devora.git
cd Devora
uv sync --extra test
uv run pytest
uvx ruff format --check src tests scripts/python scripts/ci
uvx ruff check src tests scripts/python scripts/ci

Build and smoke-test the wheel:

uv build
python scripts/ci/wheel_smoke.py

CI validates Python 3.11 and 3.14 on Ubuntu, macOS, and Windows. The wheel smoke test installs the built package into a clean environment and runs a real project initialization plus feature setup.

Architecture

The Python CLI owns installation, safe upgrades, integration selection, and deterministic feature-path setup. The connected coding agent owns repository inspection, technical reasoning, artifact authoring, implementation, and validation.

See docs/architecture.md for the detailed runtime, ownership, safety, and responsibility model.

License

Devora is available under the Apache License 2.0.