Metadata-Version: 2.4
Name: devora-cli
Version: 1.0.0
Summary: Project-aware, role-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](docs/assets/devora-banner.png)

[![CI](https://github.com/cheney369/Devora/actions/workflows/ci.yml/badge.svg)](https://github.com/cheney369/Devora/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

Devora is a project-aware workflow for AI coding agents. It adds a consistent engineering process to an existing repository, helping agents plan changes, implement them, verify the result, and prepare a clear delivery record.

Devora works with the coding agent you already use. It installs native commands and project-level workflow files without introducing a separate model runtime.

## Why Devora

- **Consistent delivery** — guide each change through Design, Build, and Review.
- **Project awareness** — work from the repository's code, documentation, and engineering conventions.
- **Role-specific guidance** — support frontend, backend, and full-stack development.
- **Traceable changes** — keep plans, tasks, progress, review results, and handoff information together.
- **Team customization** — apply reusable rules and skills at company, project, and personal scopes.
- **Agent portability** — use the same workflow across supported coding-agent integrations.

## Getting started

### 1. Install Devora

Devora requires Python 3.11 or later. Install the CLI with [uv](https://docs.astral.sh/uv/):

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

Confirm the installation:

```bash
devora --version
```

### 2. Initialize a project

Run `devora init` from the repository you want to use:

```bash
cd /path/to/project
devora init . --integration codex --role frontend --language en
```

Choose the integration that matches your coding agent and the role that matches the repository. Initialization adds Devora's workflow files; it does not modify application code.

### 3. Start your first change

Open the project with your coding agent and invoke Devora with a clear objective and any relevant sources:

```text
$devora

Implement order cancellation.

Reference material:
- ./requirements/order-cancel/
- ./docs/order-api.md
- https://www.figma.com/design/...
```

Devora accepts direct descriptions as well as references to project files, directories, specifications, API documents, issue links, and UI designs.

For integrations that use slash commands, invoke `/devora` instead of `$devora`.

### 4. Review the delivery record

Workflow artifacts are stored in a named change directory:

```text
.devora/changes/order-cancel/
├── design.md
├── tasks.md
├── summary.md
├── review.md
└── handoff/
```

Use `summary.md` to follow progress, `review.md` for the final review result, and `handoff/` for integration and delivery information.

## Workflow

```text
Design  →  Build  →  Review  →  Human approval
```

| Stage | Purpose | Main outputs |
|---|---|---|
| Design | Understand the requested change and define an implementation approach | `design.md`, `tasks.md`, `summary.md` |
| Build | Implement tasks and run the required engineering validation | Source changes, validation results, handoff material |
| Review | Check the implementation against the design and delivery requirements | `review.md`, updated `summary.md` |

The main entry point resumes the appropriate stage from the current project state. Advanced users can invoke a stage directly:

| Stage | Codex | Slash-command integrations |
|---|---|---|
| Full workflow | `$devora` | `/devora` |
| Design | `$devora-design` | `/devora-design` |
| Build | `$devora-build` | `/devora-build` |
| Review | `$devora-review` | `/devora-review` |

## Development roles

Select one role for each initialized repository:

| Role | Recommended for | Primary focus |
|---|---|---|
| `frontend` | Web and client applications | UI behavior, components, application states, API integration, and visual validation |
| `backend` | Services and server applications | Business logic, contracts, data, authorization, reliability, and integration validation |
| `full-stack` | Combined applications or end-to-end ownership | Coordinated frontend and backend delivery |

Manage the active role with the CLI:

```bash
devora role list
devora role current .
devora role use backend .
```

## Customization

Devora loads Markdown rules and agent skills from three scopes:

| Scope | Location | Typical use |
|---|---|---|
| Company | `~/.config/devora/company/` | Organization-wide engineering standards |
| Project | `<project>/.devora/custom/` | Repository-specific conventions and workflows |
| Personal | `~/.config/devora/personal/` | Individual preferences and reusable skills |

Each scope can contain:

```text
rules/                  Markdown guidance files
skills/<name>/SKILL.md  Agent skills
```

Personal configuration can also include `preferences.md`.

## Supported integrations

| Coding agent | Integration name | Main entry point |
|---|---|---|
| Codex | `codex` | `$devora` |
| Claude Code | `claude` | `/devora` |
| OpenCode | `opencode` | `/devora` |
| Cursor | `cursor` | `/devora` |
| Generic Markdown agent | `generic` | `/devora` |

List, switch, or upgrade integrations:

```bash
devora integrations
devora integration use claude .
devora integration upgrade .
```

Run `devora <command> --help` for the complete CLI reference.

## Development

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

Additional documentation:

- [Architecture](docs/architecture.md)
- [Changelog](CHANGELOG.md)
- [Issue tracker](https://github.com/cheney369/Devora/issues)

## Project status

Devora is currently in alpha. Interfaces and generated workflow files may evolve before a stable release.

## License

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