open-codev-workflow 0.1.0__py3-none-any.whl

codev_workflow/__init__.py

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

codev_workflow/__main__.py

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

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.

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."

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]

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.

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."

codev_workflow/bundle/.agents/skills/define-product/assets/brief.template.md

@@ -0,0 +1,50 @@
+# [Product or Feature Name]
+
+**Status:** Draft
+**Owner:** [name or team]
+**Last reviewed:** [YYYY-MM-DD]
+
+## Problem and users
+
+[Who has which problem, with supporting evidence.]
+
+## Desired outcome
+
+[The user or business outcome, not the proposed implementation.]
+
+## Success measures
+
+- [Observable measure and target]
+
+## Essential scenarios
+
+- [Primary scenario]
+- [Important failure or recovery scenario]
+
+## First release
+
+### Now
+
+- [Required outcome]
+
+### Next
+
+- [Plausible follow-up; not committed]
+
+### Not planned
+
+- [Explicit non-goal]
+
+## Constraints
+
+- [Business, safety, privacy, accessibility, platform, cost, or timing constraint]
+
+## Assumptions and discovery
+
+| Assumption | Evidence needed | Owner | Decision point |
+|---|---|---|---|
+| [assumption] | [experiment or data] | [owner] | [when/how decided] |
+
+## Acceptance
+
+- [ ] Outcome, scope, non-goals, and success measures accepted by the accountable human.

codev_workflow/bundle/.agents/skills/design-solution/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: design-solution
+description: Create or revise a practical technical design for a significant feature, product, migration, or cross-component change. Use when engineers need architecture, component ownership, APIs or contracts, data flow, trade-offs, risk controls, test strategy, or rollout design before implementation. Skip this skill for local low-risk changes with an obvious implementation.
+---
+
+# Design Solution
+
+Help the developer make the few technical decisions that must be shared before
+parallel implementation. Use `assets/design.template.md`; use
+`assets/decision.template.md` only for a durable cross-cutting decision that
+must outlive the design document.
+
+## 1. Establish context
+
+Read the accepted brief, relevant repository instructions, current architecture,
+code, tests, and prior decisions. Confirm the design still solves the stated
+outcome. Return to `define-product` if the outcome or scope is the real problem.
+
+State which decisions the design must settle and which details can safely remain
+with implementing engineers.
+
+## 2. Investigate before proposing
+
+Locate existing components, ownership, extension points, schemas, APIs, failure
+conventions, deployment model, and comparable implementations. Distinguish
+verified repository facts from assumptions.
+
+For material choices, present the recommended option, meaningful alternatives,
+and trade-offs. Ask the human only when alternatives change product behavior,
+an interface, persistent data, risk, cost, or ownership.
+
+## 3. Design stable boundaries
+
+Describe components in ordinary language. For every cross-component API or
+contract, define:
+
+- owner, callers, and purpose;
+- request/event/data shape or authoritative reference;
+- guarantees and caller obligations;
+- validation, errors, timeouts, and retries;
+- compatibility and migration expectations; and
+- a contract-level test or fixture when parallel work depends on it.
+
+Do not prescribe classes, private methods, file layouts, or algorithms unless
+they are genuinely architectural.
+
+## 4. Design quality and delivery
+
+Cover proportionate concerns:
+
+- security, privacy, permissions, abuse, and data retention;
+- reliability, concurrency, observability, capacity, and cost;
+- accessibility and internationalization;
+- unit, contract, integration, end-to-end, performance, and failure testing;
+- migration, feature flag, rollout, rollback, and cleanup; and
+- unresolved risks with an owner and evidence-producing next step.
+
+Prefer a thin end-to-end path that can be tested early.
+
+## 5. Review and accept
+
+Save product designs under `docs/design/` or feature-local designs under
+`docs/features/<slug>/design.md`, following repository conventions. Name an
+owner and required domain reviewers. Keep open questions visible.
+
+Mark the design `Accepted` only after material decisions are resolved and the
+human confirms it is safe to plan against. Git history records revisions.
+Implementation discoveries may update the design; explain affected work rather
+than invalidating unrelated plans automatically.
+
+## Handoff
+
+Send the accepted brief, design, API/contract references, open risks, and next
+demonstrable outcome to `plan-delivery`. Do not assign people or generate an
+exhaustive task list.

codev_workflow/bundle/.agents/skills/design-solution/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design Solution"
+  short_description: "Create a practical reviewed technical design"
+  default_prompt: "Use $design-solution to design this feature or product with clear trade-offs and contracts."

codev_workflow/bundle/.agents/skills/design-solution/assets/decision.template.md

@@ -0,0 +1,26 @@
+# [Decision title]
+
+**Status:** Proposed
+**Date:** [YYYY-MM-DD]
+**Owners:** [name or team]
+**Related design:** [link]
+
+## Context
+
+[Why this durable decision is needed.]
+
+## Decision
+
+[The chosen direction.]
+
+## Alternatives considered
+
+- **[Alternative]:** [reason rejected]
+
+## Consequences
+
+- [Benefit, cost, constraint, or follow-up]
+
+## Revisit when
+
+[New evidence or condition that should reopen the decision.]

codev_workflow/bundle/.agents/skills/design-solution/assets/design.template.md

@@ -0,0 +1,76 @@
+# [Design title]
+
+**Status:** Draft
+**Owner:** [name or team]
+**Reviewers:** [technical and specialist reviewers]
+**Brief:** [link]
+**Last reviewed:** [YYYY-MM-DD]
+
+## Summary
+
+[Recommended solution and why.]
+
+## Goals and non-goals
+
+### Goals
+
+- [goal]
+
+### Non-goals
+
+- [non-goal]
+
+## Current system and evidence
+
+[Relevant components, code, data, constraints, and verified references.]
+
+## Proposed design
+
+### Components and ownership
+
+| Component | Responsibility | Owner | Existing or new |
+|---|---|---|---|
+| [component] | [responsibility] | [owner] | [state] |
+
+### Data and control flow
+
+[Explain the important end-to-end path.]
+
+### APIs and contracts
+
+| API/contract | Owner | Consumers | Guarantees | Errors/timeouts | Compatibility | Test/fixture |
+|---|---|---|---|---|---|---|
+| [name/link] | [owner] | [consumers] | [behavior] | [behavior] | [policy] | [evidence] |
+
+## Alternatives and trade-offs
+
+| Option | Benefits | Costs/risks | Decision |
+|---|---|---|---|
+| [option] | [benefits] | [costs] | [chosen/rejected] |
+
+## Quality and risk
+
+- **Security/privacy:** [analysis]
+- **Reliability/concurrency:** [analysis]
+- **Observability/capacity/cost:** [analysis]
+- **Accessibility/internationalization:** [analysis]
+
+## Test strategy
+
+- [unit/contract/integration/end-to-end/performance/failure evidence]
+
+## Migration, rollout, rollback, and cleanup
+
+[Safe intermediate states and recovery.]
+
+## Open questions
+
+| Question | Owner | Evidence needed | Blocking? |
+|---|---|---|---|
+| [question] | [owner] | [evidence] | [yes/no] |
+
+## Acceptance
+
+- [ ] Material decisions resolved.
+- [ ] Required domain reviews complete.
+- [ ] Accountable human accepts planning against this design.

codev_workflow/bundle/.agents/skills/launch-product/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: launch-product
+description: Prepare and guide a safe release of a completed feature or product through readiness review, migration, feature flags, internal testing, staged rollout, observability, rollback, and post-launch learning. Use when code is approaching deployment, a team needs a launch checklist or rollout plan, or production evidence must determine expansion. Do not deploy, publish, or enable users without explicit human authorization.
+---
+
+# Launch Product
+
+Treat launch as the start of a learning loop, not the end of implementation. Use
+`assets/launch-plan.template.md` for material launches; a pull-request checklist
+is sufficient for low-risk routine releases.
+
+## 1. Classify launch risk
+
+Assess blast radius, reversibility, novelty, data changes, dependency changes,
+security/privacy impact, user visibility, operational maturity, and regulatory
+requirements. State required approvers and evidence. Risk, not code size,
+determines rigor.
+
+## 2. Verify readiness
+
+Check proportionately:
+
+- accepted outcome and release scope;
+- reviewed code and green required validation;
+- exact artifact/configuration being released;
+- migration and backward/forward compatibility;
+- security, privacy, legal, accessibility, and support readiness;
+- dashboards, logs, alerts, SLOs, capacity, runbook, and on-call ownership;
+- feature flag or other containment mechanism; and
+- tested rollback or safe-disable procedure.
+
+Unverified critical items are blockers. Record owner and evidence for every
+exception; never turn an unchecked box into approval.
+
+## 3. Plan progressive exposure
+
+Define stages appropriate to the product: local/staging, team dogfood, internal
+users, trusted testers, small production percentage, broader rollout, and full
+availability. For every stage specify:
+
+- eligible users or traffic;
+- duration or minimum evidence window;
+- product success and system health measures;
+- explicit proceed, pause, and rollback thresholds;
+- monitoring owner and decision maker; and
+- communications or support actions.
+
+Prefer configuration or feature-flag changes over rebuilding different
+artifacts between stages.
+
+## 4. Execute only with authorization
+
+Present the readiness result and next rollout step. Obtain explicit human
+authorization before deploying, publishing, migrating data, changing a flag, or
+expanding exposure. Observe the named signals after every stage. Pause or roll
+back when thresholds fail; do not optimize for completing the rollout.
+
+## 5. Learn and close
+
+After the evidence window, compare outcomes to the brief. Record unexpected
+behavior, incidents, support feedback, cost, and follow-up work. Remove temporary
+flags, compatibility paths, and migration tooling when safe. Update product or
+design documentation when the learned behavior changes future decisions.
+
+Return a concise decision: expand, hold, roll back, or revise—plus evidence and
+owners for remaining actions.

codev_workflow/bundle/.agents/skills/launch-product/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Launch Product"
+  short_description: "Prepare, release, observe, and learn safely"
+  default_prompt: "Use $launch-product to assess readiness and plan a safe, measurable rollout."

codev_workflow/bundle/.agents/skills/launch-product/assets/launch-plan.template.md

@@ -0,0 +1,48 @@
+# [Product or Feature] Launch Plan
+
+**Status:** Draft
+**Launch owner:** [name]
+**Engineering owner:** [name/team]
+**Brief/design:** [links]
+**Release artifact/config:** [immutable identifier]
+**Risk:** [low/normal/high/critical]
+
+## Release outcome
+
+[What is being released, to whom, and which success measure it tests.]
+
+## Readiness evidence
+
+| Area | Required evidence | Owner | Status/link |
+|---|---|---|---|
+| Product and UX | [acceptance/dogfood] | [owner] | [state] |
+| Engineering | [review/CI/integration] | [owner] | [state] |
+| Security/privacy/legal | [review or Not required with reason] | [owner] | [state] |
+| Data and compatibility | [migration/rehearsal] | [owner] | [state] |
+| Operations | [dashboards/alerts/runbook/capacity] | [owner] | [state] |
+| Rollback | [tested disable/revert procedure] | [owner] | [state] |
+
+## Rollout stages
+
+| Stage | Audience/traffic | Minimum evidence window | Success and health thresholds | Pause/rollback threshold | Monitor | Approver |
+|---|---|---|---|---|---|---|
+| Dogfood | [group] | [duration/evidence] | [thresholds] | [thresholds] | [owner] | [human] |
+
+## Migration and compatibility
+
+[Order, dual-read/write, version skew, recovery, and cleanup.]
+
+## Communications and support
+
+- [Users, support, incident response, release notes]
+
+## Rollback procedure
+
+1. [Exact safe-disable or rollback action]
+2. [Verification and communication]
+
+## Post-launch review
+
+**Evidence date:** [date/window]
+**Decision:** Expand / Hold / Roll back / Revise
+**Learning and follow-up:** [links and owners]