open-codev-workflow 0.1.0__tar.gz

open_codev_workflow-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Martin Urban
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

open_codev_workflow-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: open-codev-workflow
+Version: 0.1.0
+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,codex,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)
+
+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.0-py3-none-any.whl
+# or
+uv tool install ./dist/open_codev_workflow-0.1.0-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.
+
+## What gets installed
+
+```text
+my-project/
+├── AGENTS.md                         # a managed policy block; local text survives
+├── .agents/skills/                   # seven lifecycle skills
+├── .opencode/agents/                 # orchestrator, builder, reviewer
+├── .opencode/opencode.json           # safely merged; existing agent settings survive
+├── 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 adapter. Use `--platform opencode`
+or `--platform all` for the three-agent OpenCode topology. Core skills and
+human/AI workflow references are installed for every platform.
+
+## 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.

open_codev_workflow-0.1.0/README.md

@@ -0,0 +1,121 @@
+<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)
+
+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.0-py3-none-any.whl
+# or
+uv tool install ./dist/open_codev_workflow-0.1.0-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.
+
+## What gets installed
+
+```text
+my-project/
+├── AGENTS.md                         # a managed policy block; local text survives
+├── .agents/skills/                   # seven lifecycle skills
+├── .opencode/agents/                 # orchestrator, builder, reviewer
+├── .opencode/opencode.json           # safely merged; existing agent settings survive
+├── 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 adapter. Use `--platform opencode`
+or `--platform all` for the three-agent OpenCode topology. Core skills and
+human/AI workflow references are installed for every platform.
+
+## 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.

open_codev_workflow-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "open-codev-workflow"
+version = "0.1.0"
+description = "Human-guided AI software delivery for real repositories."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+authors = [{ name = "Martin Urban" }]
+keywords = ["ai", "developer-tools", "software-delivery", "codex", "opencode"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/urban233/CoDev"
+Repository = "https://github.com/urban233/CoDev"
+Issues = "https://github.com/urban233/CoDev/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "mypy>=1.15",
+  "ruff>=0.11",
+  "twine>=6.1",
+]
+
+[project.scripts]
+codev = "codev_workflow.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+codev_workflow = [
+  "bundle/AGENTS.md",
+  "bundle/.agents/skills/*/SKILL.md",
+  "bundle/.agents/skills/*/agents/*.yaml",
+  "bundle/.agents/skills/*/assets/*",
+  "bundle/.agents/skills/*/references/*",
+  "bundle/.agents/skills/*/scripts/*",
+  "bundle/.opencode/agents/*.md",
+  "bundle/docs/*.md",
+  "bundle/docs/for-ai/*.md",
+  "bundle/docs/handbooks/*.md",
+  "bundle/evals/development-workflow/*.json",
+  "bundle/scripts/*.py",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+exclude = ["src/codev_workflow/bundle"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+files = ["src/codev_workflow", "tests"]
+exclude = "src/codev_workflow/bundle/"

open_codev_workflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

open_codev_workflow-0.1.0/src/codev_workflow/__init__.py

@@ -0,0 +1,5 @@
+"""CoDev: human-guided AI software delivery."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

open_codev_workflow-0.1.0/src/codev_workflow/__main__.py

@@ -0,0 +1,4 @@
+from codev_workflow.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

open_codev_workflow-0.1.0/src/codev_workflow/bundle/.agents/skills/build-change/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: build-change
+description: Pair with a developer to investigate, plan, implement, test, and prepare one bounded code change, bug fix, refactor, or delivery-plan work item. Use when the user wants hands-on AI-assisted coding with frequent checkpoints and human control rather than a long autonomous implementation loop. Ground every plan in the current repository and keep changes small and reviewable.
+---
+
+# Build Change
+
+Work as an interactive pair engineer. The human owns intent and acceptance; the
+AI investigates, proposes, edits, validates, and explains. Use
+`assets/implementation-plan.template.md` only when work spans sessions, affects
+several components, or needs a reviewed written plan.
+
+## 1. Frame the change
+
+Read the issue or work item, relevant brief/design/API references, repository
+instructions, and current Git state. Before editing, show a compact inline focus
+card:
+
+- **Change:** intended outcome;
+- **Success:** observable acceptance behavior;
+- **Non-goals:** explicit exclusions;
+- **Allowed scope:** expected components or paths;
+- **Validation:** checks that will provide acceptance evidence;
+- **Stop if:** material decisions or conditions that require the human; and
+- **Work style:** `Pair` by default, or `Bounded delegate` only for isolated,
+  well-specified, testable, reversible work.
+
+For an obvious low-risk change, keep this inline. Do not manufacture planning
+documents. Treat the allowed scope as a drift boundary: surface a needed
+expansion before editing outside it.
+
+## 2. Ground the plan
+
+Inspect actual files, symbols, tests, build commands, conventions, ownership,
+and recent related changes before proposing edits. Identify mismatches between
+the request and repository reality.
+
+A new request does not silently supersede an accepted brief, design, API, or
+repository policy. When they conflict, stop, show the exact conflict, recommend
+the safest resolution, and obtain an explicit human decision in the owning
+artifact before implementation.
+
+Propose the smallest coherent change, expected files, test approach, risks, and
+any intentional follow-up. Obtain a human decision before editing when the plan
+introduces or changes an API, data model, dependency, security behavior,
+architecture, user-visible scope, or destructive operation. Otherwise announce
+the plan and proceed interactively.
+
+## 3. Implement a small change
+
+Prefer one review purpose. As a soft warning, reconsider the slice when it
+exceeds roughly 400 non-generated changed lines or eight files; generated code,
+mechanical migrations, and tightly coupled tests may justify more. Split only
+when each part remains buildable and useful.
+
+Reuse repository patterns. Add or update tests with the behavior. Do not weaken
+tests, invent missing APIs, silently expand scope, or edit accepted product and
+design decisions to make implementation easier.
+
+Share concise progress at meaningful boundaries. Do not run unattended retry
+loops. After two failed attempts with the same root cause, stop, present the
+evidence, and agree on the next approach with the human.
+
+## 4. Validate and inspect
+
+Run the repository's formatter, static checks, affected tests, and proportionate
+broader tests. Report exact commands, outcomes, and any checks that could not run.
+
+Review the complete diff for accidental files, debug code, weakened assertions,
+security or compatibility regressions, unnecessary complexity, and stale docs.
+Map important acceptance criteria to evidence; formal requirement IDs are only
+needed when policy or risk requires them.
+
+## 5. Prepare review
+
+Return a compact evidence receipt:
+
+- **Delivered:** outcome and observable behavior;
+- **Changed:** files and components;
+- **Validation actually run:** exact commands and outcomes;
+- **Acceptance evidence:** criteria mapped to evidence;
+- **Scope deviations:** none, or accepted deviations;
+- **Known limitations:** risks and follow-up work; and
+- **Review state:** independent review status and rollout implications.
+
+For normal or higher-risk work, invoke `review-change` in a fresh context when
+available. The implementing AI never declares its own work approved. The human
+must inspect the diff and explicitly authorize commit, merge, publication, or
+release actions according to repository policy.
+
+## Stop conditions
+
+Stop and ask for one precise decision when required behavior conflicts, a
+material design choice is missing, the repository is unexpectedly stale,
+permissions or a dependency are unavailable, concurrent changes collide, or
+safe validation cannot be produced. Include evidence and safe alternatives.

open_codev_workflow-0.1.0/src/codev_workflow/bundle/.agents/skills/build-change/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build Change"
+  short_description: "Pair with AI to plan, implement, and verify a change"
+  default_prompt: "Use $build-change to work with me interactively on this bounded code change."

open_codev_workflow-0.1.0/src/codev_workflow/bundle/.agents/skills/build-change/assets/implementation-plan.template.md

@@ -0,0 +1,51 @@
+# [Work item] Implementation Plan
+
+**Status:** Draft
+**Owner:** [developer]
+**Reviewer:** [independent reviewer]
+**Risk:** [low/normal/high/critical]
+**Base commit:** [Git commit]
+**Issue/work item:** [link or ID]
+**Brief/design/API:** [links or Not needed]
+
+## Focus card
+
+- **Change:** [Intended outcome]
+- **Success:** [Observable acceptance behavior]
+- **Non-goals:** [Explicit exclusions]
+- **Allowed scope:** [Expected components or paths]
+- **Validation:** [Checks that provide acceptance evidence]
+- **Stop if:** [Material decision or condition requiring the human]
+- **Work style:** [Pair / Bounded delegate with reason]
+
+
+## Repository evidence
+
+- `[path/symbol]`: [verified fact]
+
+## Proposed change
+
+1. [Small repository-grounded step and test]
+
+## Validation
+
+- `[exact command]` -> [expected evidence]
+
+## Risks and rollout
+
+- [Risk, containment, feature flag, compatibility, or rollback]
+
+## Decisions needed
+
+- [None, or one material decision with recommendation]
+
+## Completion evidence
+
+- **Delivered:** [Outcome and observable behavior]
+- **Changed:** [Files and components]
+- **Head commit/snapshot:** [Value]
+- **Validation actually run:** [Exact commands and outcomes]
+- **Acceptance evidence:** [Criterion -> evidence]
+- **Scope deviations:** [None or accepted deviations]
+- **Known limitations:** [None, risks, or follow-up links]
+- **Review state:** [Not reviewed / review result and rollout implications]

open_codev_workflow-0.1.0/src/codev_workflow/bundle/.agents/skills/define-product/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: define-product
+description: Turn a software idea, product proposal, or feature request into a clear product or feature brief and select the lightest safe workflow. Use when a developer needs help clarifying users, outcomes, scope, success measures, constraints, assumptions, or whether work is a quick change, feature, or product. Do not design the technical solution or create implementation tasks.
+---
+
+# Define Product
+
+Guide the developer from an idea to an accepted brief. Explain the purpose of
+each step in plain language and keep the conversation focused on product intent.
+
+Use `assets/brief.template.md` when a durable brief is useful.
+
+## 1. Choose the workflow size
+
+Recommend one path and explain why:
+
+- **Quick change:** local, reversible, low-risk work with obvious acceptance.
+  Hand off directly to `build-change`; an issue is enough.
+- **Feature:** a user-visible or cross-file outcome with limited architectural
+  impact. Create a feature brief, then use `design-solution` only if needed.
+- **Product:** a new product, major capability, cross-team effort, migration, or
+  high-risk change. Create a product brief and continue through all lifecycle
+  skills.
+
+Risk overrides size. Security, privacy, permissions, public APIs, persistent
+data, billing, compliance, and destructive operations require at least the
+feature path and an explicit design review.
+
+## 2. Discover intent
+
+Read supplied material completely. Inspect existing product documentation when
+available. Establish:
+
+- target users and their problem;
+- desired outcome and measurable evidence of success;
+- essential scenarios and failure expectations;
+- first-release scope and explicit non-goals;
+- fixed business, legal, safety, accessibility, platform, cost, and timing
+  constraints; and
+- assumptions that need evidence before committing to the full solution.
+
+Never fabricate a numerical target. When no baseline or accountable target
+exists, name the measure, define how to establish its baseline, and leave target
+selection as an explicit product decision before accepting the brief.
+
+Ask at most four related questions at once. Recommend an answer when evidence
+supports one. Do not ask for repository facts that can be inspected later.
+
+## 3. Shape the smallest useful release
+
+Prefer one end-to-end outcome over a catalogue of components. Separate:
+
+- **Now:** required to demonstrate value;
+- **Next:** plausible follow-up, not committed;
+- **Not planned:** deliberately excluded.
+
+If the central user or outcome is still unknown, propose a bounded discovery
+experiment rather than pretending the product is ready for engineering.
+
+## 4. Save and accept the brief
+
+For a feature, write `docs/features/<slug>/brief.md`. For a product, write
+`docs/product/<slug>/brief.md`. Adapt to an existing repository convention
+instead of creating a parallel structure.
+
+Set `Status: Draft` until the human confirms the outcome, scope, non-goals, and
+success measures. Then set `Status: Accepted`. Git history is the revision
+record; do not invent a second revision scheme.
+
+## Handoff
+
+Recommend the next action:
+
+- Quick change -> `build-change`
+- Feature with no material design choice -> `plan-delivery` or `build-change`
+- Feature with architectural/risk decisions -> `design-solution`
+- Product -> `design-solution`
+
+Never convert the brief into architecture, staffing, or code-level tasks.

open_codev_workflow-0.1.0/src/codev_workflow/bundle/.agents/skills/define-product/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Define Product"
+  short_description: "Turn an idea into a clear product or feature brief"
+  default_prompt: "Use $define-product to shape this idea into a clear, testable product or feature brief."