Metadata-Version: 2.4
Name: devora-cli
Version: 0.4.0
Summary: Project-aware spec-driven development workflows for coding agents.
Project-URL: Homepage, https://github.com/cheney369/Devora
Project-URL: Repository, https://github.com/cheney369/Devora
Project-URL: Issues, https://github.com/cheney369/Devora/issues
Project-URL: Changelog, https://github.com/cheney369/Devora/blob/main/CHANGELOG.md
Author: cheney369
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,coding-agents,developer-tools,requirements,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.16.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Devora

[English](README.md) | [简体中文](README.zh-CN.md)

![Devora — from product intent to reviewed delivery](docs/assets/devora-banner.png)

**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:

```bash
uv tool install devora-cli
devora --version
```

Initialize an existing repository:

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

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

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

Then continue through the delivery flow:

```text
$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

| Integration | Initialize with | Installed location | Invoke |
|---|---|---|---|
| Codex | `--integration codex` | `.agents/skills/devora-*/SKILL.md` | `$devora-*` |
| Claude Code | `--integration claude` | `.claude/skills/devora-*/SKILL.md` | `/devora-*` |
| OpenCode | `--integration opencode` | `.opencode/commands/devora-*.md` | `/devora-*` |
| Cursor | `--integration cursor` | `.cursor/commands/devora-*.md` | `/devora-*` |
| Generic Markdown | `--integration generic` | `.devora/commands/devora.*.md` | `/devora.*` |

Codex is the default:

```bash
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:

```bash
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

```text
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
```

| Stage | Result | Human involvement |
|---|---|---|
| `project-context` | Durable, evidence-based repository snapshot | Optional |
| `constitution` | Project-specific delivery rules | Only when rules need decisions |
| `specify` | Traceable intake, specification, and human summary | Approve scope or clarify |
| `clarify` | Resolved product ambiguity | Only material product decisions |
| `plan` | Technical plan and first-class test cases | Review material trade-offs |
| `tasks` | Dependency-aware executable work | Usually none |
| `analyze` | Read-only consistency and readiness report | Usually none |
| `resolve` | Synchronized artifact repairs and re-analysis | Only true user decisions |
| `implement` | Code, validation evidence, and task state | External actions if blocked |
| `review` | Independent pre-PR findings and approval packet | Final approval or changes |

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:

```bash
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:

```bash
devora init . --script-type py
```

The Bash backend remains available for compatibility:

```bash
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.

```bash
uv tool upgrade devora-cli

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

Devora uses separate ownership manifests:

```text
.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:

```bash
devora integration upgrade . --force
```

Manage integrations directly:

```bash
devora integration list
devora integration use cursor .
devora integration uninstall cursor .
```

## Installed project structure

```text
.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:

```bash
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

```bash
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:

```bash
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](docs/architecture.md) for the detailed runtime,
ownership, safety, and responsibility model.

## License

Devora is available under the [Apache License 2.0](LICENSE).
