Metadata-Version: 2.4
Name: devora-cli
Version: 0.3.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

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:

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

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

Upgrade an existing installation:

```bash
uv tool upgrade devora-cli
```

Install a specific GitHub release before or without using PyPI:

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

## Install for development

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

## Initialize a project

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

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

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

Choose another integration when needed:

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

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

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

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