Metadata-Version: 2.4
Name: open-codev-workflow
Version: 0.1.4
Summary: Human-guided AI software delivery for real repositories.
Author: Martin Urban
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/urban233/CoDev
Project-URL: Repository, https://github.com/urban233/CoDev
Project-URL: Issues, https://github.com/urban233/CoDev/issues
Keywords: ai,developer-tools,software-delivery,antigravity,codex,junie,opencode
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: mypy>=1.15; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/codev-mark.svg" width="96" height="96" alt="CoDev mark">
</p>

<h1 align="center">CoDev</h1>

<p align="center"><strong>Human-guided AI software delivery.</strong></p>

![Active Feature Development](https://img.shields.io/badge/Project_State-Active_Feature_Development-brightgreen?style=flat-square)
![AI-driven](https://img.shields.io/badge/AI_Use-AI--driven-orange?style=flat-square)
![CI](https://img.shields.io/github/actions/workflow/status/urban233/CoDev/ci.yml?branch=main&label=CI&style=flat-square)
![PyPI version](https://img.shields.io/pypi/v/open-codev-workflow?style=flat-square)
![Python versions](https://img.shields.io/pypi/pyversions/open-codev-workflow?style=flat-square)
![License](https://img.shields.io/github/license/urban233/CoDev?style=flat-square)
![Latest release](https://img.shields.io/github/v/release/urban233/CoDev?style=flat-square)
![GitHub stars](https://img.shields.io/github/stars/urban233/CoDev?style=flat-square)
![GitHub issues](https://img.shields.io/github/issues/urban233/CoDev?style=flat-square)

CoDev installs a small, production-minded collaboration system into any Git
repository. It helps a developer and AI move through four understandable steps:
**Understand, Build, Review, and Ship**. It supports bounded three-agent
execution without turning product development into an unattended coding loop.

## Why CoDev

- One workflow for solo developers and multi-developer teams.
- Repository-grounded plans instead of invented APIs or architecture.
- A bounded builder and an independent, read-only reviewer.
- Human authority over material decisions, merge, deployment, and rollout.
- Versioned, conflict-aware installation across existing repositories.
- No runtime dependency in the software being built.

## Quick start

CoDev is a Python 3.11+ command-line tool. Target repositories may use any
language or build system. Install it with an isolated tool manager; `pipx` and
`uv tool` are the two supported, primary installation methods. Neither adds
CoDev or its dependencies to a target repository.

### Install from PyPI

```shell
pipx install open-codev-workflow
# or
uv tool install open-codev-workflow
```

### Install from a wheel

For private, air-gapped, or pre-release distribution, install the supplied
wheel directly instead of publishing it to a package index:

```shell
pipx install ./dist/open_codev_workflow-0.1.1-py3-none-any.whl
# or
uv tool install ./dist/open_codev_workflow-0.1.1-py3-none-any.whl
```

Store the wheel with its SHA-256 checksum in a controlled artifact location.
The development workflow for building a wheel is documented below.

### Initialize a repository

```shell
codev init --target ../my-project --platform all
codev check --target ../my-project
```

To preview or apply a later bundle update:

```shell
codev diff --target ../my-project
codev update --target ../my-project
codev remove --target ../my-project --dry-run
```

`init`, `diff`, and `update` preflight the entire operation. A locally modified
managed file becomes a visible conflict; CoDev never silently replaces it.

## GitHub Pull Request reviews

The installed `pr-review` skill reviews an existing GitHub Pull Request and can
prepare validated inline comments for the exact PR head. It uses the GitHub CLI
credential store by default, so agents do not need to read or print a token.

### Install and authenticate GitHub CLI on Windows

Install the official package from PowerShell with WinGet:

```powershell
winget install --id GitHub.cli --source winget
```

Open a new Windows Terminal window after installation, then verify and sign in:

```powershell
gh --version
gh auth login --web
gh auth status --active
```

Choose `GitHub.com`, the HTTPS protocol, and the browser login flow. `gh` stores
the credential using the Windows credential store when available. See the
[official Windows installation guide](https://github.com/cli/cli/blob/trunk/docs/install_windows.md)
and [`gh auth login` documentation](https://cli.github.com/manual/gh_auth_login).

Run the PR publisher in dry-run mode first:

```powershell
python .agents\skills\pr-review\scripts\publish_review.py `
  --repo OWNER/REPO `
  --pr 123 `
  --review review.json
```

The publisher automatically uses authenticated `gh api` when no
`GITHUB_TOKEN` or `GH_TOKEN` is set. Use `--auth gh` to require that backend or
`--auth token` for headless environments that provide a token variable. Add
`--publish` only after explicitly authorizing a GitHub review, and use
`--submit comment` only when it should be submitted immediately.

If a desktop agent does not inherit the Windows machine PATH, the publisher
also checks the standard `C:\\Program Files\\GitHub CLI\\gh.exe` location. For a
custom installation, set `CODEV_GH_PATH` to the full path of `gh.exe`.

To copy the already-authenticated `gh` credential into `GH_TOKEN` for the
current PowerShell process and the CLI started from it, dot-source the bundled
helper:

```powershell
. .agents\\skills\\pr-review\\scripts\\set-github-token.ps1
```

The helper calls `gh auth token` without printing the result and does not
persist it. The `gh` credential must be valid in the same process context. This
is useful for a CLI that needs `GH_TOKEN`; launch that CLI from the shell where
the helper has been dot-sourced. Do not put the token in a repository file or
command-line argument.

One-line equivalent:

```powershell
$g=Get-Command gh -ErrorAction SilentlyContinue;if($g){$p=$g.Source}else{$p='C:\\Program Files\\GitHub CLI\\gh.exe'};$env:GH_TOKEN=(& $p auth token --hostname github.com 2>$null).Trim()
```

Fetch the complete GitHub PR context before asking an agent to review it:

```powershell
python .agents\\skills\\pr-review\\scripts\\publish_review.py `
  --repo OWNER/REPO `
  --pr 123 `
  --fetch `
  --output-dir .codev\\pr-review\\123
```

This writes PR metadata, the patch, changed files, commits, reviews, comments,
and check runs. Use repeated `--include metadata`, `--include diff`, or other
parts to fetch a smaller set.

The installed Junie project command is also available directly inside Junie:

```text
/pr-review repo=OWNER/REPO pr=123
```

Project-specific Junie commands live under `.junie/commands`, so this command
is versioned with the repository and appears in Junie’s `/` command list.

## What gets installed

```text
my-project/
├── AGENTS.md                         # a managed policy block; local text survives
├── .agents/skills/                   # lifecycle, PR, and specialist review skills
├── .agents/agents/                   # Antigravity subagents
├── .opencode/agents/                 # orchestrator, builder, reviewer
├── .opencode/opencode.json           # safely merged; existing agent settings survive
├── .junie/agents/                    # Junie subagents
├── docs/                             # workflow, prompts, handbooks, cookbook
├── evals/development-workflow/       # behavioral scenarios
├── scripts/                          # deterministic validators
└── .codev/lock.json                # installed version and source hashes
```

Use `--platform codex` to omit the OpenCode, Junie, and Antigravity adapters.
Use `--platform opencode`, `--platform junie`, or `--platform antigravity` to
select one adapter, or use `--platform all` for every supported platform. Core
skills and human/AI workflow references are installed for every platform.

To add an adapter to an existing installation, pass it to `update`, for example
`codev update --platform junie`. Use `diff --platform junie` to preview the
platform expansion first.

The Antigravity adapter follows its official workspace location:
`.agents/agents/<name>.md`.

## Design principles

1. **Local at use time.** Agents read ordinary files in the target repository.
2. **Central at maintenance time.** This repository is the canonical source.
3. **Human at authority boundaries.** Automation supplies evidence, not approval.
4. **Small by default.** Deeper design and delivery planning appear only when
   risk or coordination requires them.
5. **Safe to adopt.** Existing instructions and OpenCode settings are preserved.

Read [Architecture](docs/architecture.md) for the distribution model,
[Adoption](docs/adoption.md) for rollout guidance, and
[Brand](docs/brand.md) for the visual and writing system.

## Development

```shell
python -m unittest discover -s tests -v
python -m compileall -q src tests
python -m codev_workflow --version
```

Optional development checks:

```shell
ruff check .
ruff format --check .
mypy
python -m build
```

CoDev is licensed under BSD-3-Clause.
