devora-cli 0.3.0

Project-aware spec-driven development workflows for coding agents.

Devora

Devora installs a project-aware, spec-driven development workflow into coding agents.

Devora is a workflow tool—not a code-search engine, RAG system, or agent runtime. The CLI installs instructions, templates, and small path/state scripts. The connected coding agent reads the real project, produces the workflow artifacts, implements the code, and runs validation.

The main difference is when project understanding happens:

optional project context
    -> request
    -> scoped impact analysis
    -> spec
    -> plan
    -> tasks
    -> analyze
    -> resolve when needed
    -> implement
    -> review and human PR approval

Impact analysis is an internal step of specify, not another command the user has to manage.

Status

Devora is in its production-workflow milestone. The current CLI installs the requirement, implementation, validation, and pre-PR review flow for Codex, Claude Code, or a generic Markdown-based agent integration.

Install

Install the published CLI from PyPI with uv:

uv tool install devora-cli
devora --version

Upgrade an existing installation:

uv tool upgrade devora-cli

Install a specific GitHub release before or without using PyPI:

uv tool install \
  git+https://github.com/cheney369/Devora.git@v0.3.0

Install for development

uv sync --extra test
uv run devora --version

Initialize a project

Codex is the default integration. Initialize an existing project from its root:

devora init . --integration codex

Choose a default artifact language when useful. auto is the default and locks each feature to the dominant product-input language:

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

Choose another integration when needed:

devora init . --integration claude
devora init . --integration generic

The installation creates shared workflow state under .devora/ and agent-specific commands under:

Integration	Command location	Invocation style
Codex	.agents/skills/devora-*/SKILL.md	$devora-* or natural language
Claude Code	.claude/skills/devora-*/SKILL.md	/devora-*
Generic	.devora/commands/devora.*.md	/devora.*

Existing, modified Devora-managed files are preserved by default. Use --force to refresh managed templates and commands. .devora/memory/constitution.md is never overwritten after creation.

After upgrading an existing installation with --force, new features receive the current artifact set automatically. To bring an active pre-0.3 feature into the production review flow, run plan, tasks, and analyze again; the plan setup backfills missing intake, summary, and test-case templates without deleting the existing specification.

Workflow

For an existing or complex project, optionally initialize durable project context first:

For Codex, explicitly mention the installed Skill with $:

$devora-project-context

Typing /devora-project-context does not invoke a Codex Skill. Codex reserves its slash menu for supported app/CLI commands; Skills use $skill-name mentions or matching natural language.

Then use the familiar flow:

$devora-constitution
$devora-specify <feature request>
$devora-clarify          # optional
$devora-plan
$devora-tasks
$devora-analyze
$devora-resolve          # when analysis is NOT_READY
$devora-implement
$devora-review           # independent pre-PR gate and human approval

specify accepts a short request or a package of documents, images, designs, tickets, links, API descriptions, and user notes. The connected agent reads those sources and records traceability in intake.md; Devora does not implement its own document parser.

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

analyze writes analysis.md without changing business code or authoritative feature documents. Findings are routed to the Agent, the user, or an external owner. resolve automatically repairs engineering issues, asks the user only for genuine product decisions, synchronizes the affected workflow documents, and re-checks readiness. review independently checks the diff and final gates, produces review.md, and requires explicit human approval before the change set is called PR-ready.

project-context asks the coding agent to inspect the current workspace and write .devora/memory/project-context.md. If that file does not exist, specify still proceeds and performs request-scoped project reading before it writes the feature specification.

Installed project structure

.devora/
├── init-options.json
├── integrations/
├── memory/
│   ├── constitution.md
│   └── project-context.md       # created only when the optional command runs
├── scripts/bash/
└── 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

Task checkboxes represent full completion, not merely code written. Every task separately records implementation and validation state; a task can be checked only after its validation passes and all dependencies are complete.

Design boundary

Devora owns:

• workflow progression;
• agent instruction templates;
• artifact templates and inheritance rules;
• deterministic feature-path setup and prerequisite checks.

The coding agent owns:

• searching and reading code;
• understanding project architecture;
• request-scoped impact analysis;
• authoring specs, plans, and tasks;
• implementation and testing.

See docs/architecture.md for the detailed responsibility boundary and runtime model.