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

codev_workflow/bundle/.agents/skills/plan-delivery/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: plan-delivery
+description: Turn an accepted product or feature brief and any required design into a lightweight, team-profile-aware multi-developer delivery plan. Use when a team needs outcome-based milestones, unassigned capability lanes or ready work items, owners, independent reviewers, simple dependencies, integration checkpoints, WIP limits, risks, or rolling-wave planning. Do not create a separate architecture or capacity bureaucracy.
+---
+
+# Plan Delivery
+
+Create a plan that helps a team choose the next useful work, not a prediction of
+every future edit. Use `assets/delivery-plan.template.md` when the repository
+has no external project tracker.
+
+## 1. Verify planning inputs
+
+Read the accepted brief and applicable design. Confirm the next outcome, fixed
+contracts, important risks, current commitments, and required reviewers. Return
+unresolved product questions to `define-product` and architectural questions to
+`design-solution`.
+
+Classify uncertain facts before planning:
+
+- **fixed:** accepted product or architectural decisions;
+- **hard blocker:** a missing decision or contract that prevents a specific item
+  from starting safely;
+- **risk track:** evidence that can be retired independently without blocking
+  unrelated work;
+- **staffing input:** capability, capacity, ownership, or reviewer information;
+  and
+- **deferred:** a decision that is not needed for the current milestone.
+
+Do not call a risk track, staffing input, or deferred decision a blocker unless
+it actually prevents the named work from starting.
+
+### Team-profile gate
+
+Headcount is not a delivery profile. Do not infer a developer's skills,
+availability, component ownership, review authority, or security/domain
+qualification from a team size, title, or anonymous label.
+
+Before assigning ready work, establish the smallest useful profile for each
+developer: stable name or label, relevant strengths, current capacity or WIP,
+component/API ownership, and independent-review restrictions. Inspect existing
+ownership and tracker facts first; ask only for missing information.
+
+If profiles are incomplete:
+
+1. recommend the next milestone and show **unassigned capability lanes**, not
+   `Developer 1`, `Developer 2`, or similar placeholders;
+2. show only candidate concurrency, conditional on named contracts or fixtures;
+3. do not claim that work items are ready or assign reviewers; and
+4. ask exactly one recommendation-led question for the missing team profile.
+
+When the human explicitly asks for an initial milestone framing first, provide
+that framing as an unassigned planning brief, then make the team profile the
+single remaining input before producing assignments.
+
+## 2. Define outcome milestones
+
+Each milestone must demonstrate observable value or retire a named risk, such as
+"internal user completes the primary workflow." Avoid component-completion
+milestones such as "backend done."
+
+For a requested first **useful product** milestone, name the target user, the
+observable action, and the durable result. A foundation-only milestone is valid
+when it retires a named risk, but label it as an enabling or risk-retirement
+milestone rather than presenting it as user value. Include the smallest
+in-scope product object when that is necessary to make the demonstration useful.
+
+Plan the current milestone in detail. Keep later milestones coarse and revise
+them using evidence from working software.
+
+## 3. Create reviewable work items
+
+Before team profiles are available, create only capability lanes. For every lane
+that could proceed concurrently, name the accepted API, schema, decision, or
+contract fixture that makes it safe. If no such authority exists, state
+**Blocked by** the missing contract; do not imply parallelism from technical
+layer names alone.
+
+Each current work item must include:
+
+- outcome and acceptance criteria;
+- relevant design/API links;
+- owner and independent reviewer;
+- dependencies and integration checkpoint;
+- risk level: low, normal, high, or critical;
+- expected validation; and
+- status: discovery, ready, in progress, review, blocked, or done.
+
+A work item should normally produce one small pull request or a short stack of
+independently valid pull requests. Split by behavior, not by technical layer.
+Use a bounded discovery item when a needed contract cannot be resolved from
+accepted authority. Never turn an unresolved decision into an implementation
+assignment.
+
+Use only ordinary dependency language:
+
+- **Blocked by:** work cannot begin safely.
+- **Integrates with:** work can proceed against an agreed contract or fixture;
+  integration happens later.
+- **Lands after:** source-control or migration order matters.
+
+## 4. Coordinate the team
+
+Default maximum work in progress to one implementation item per developer.
+Assign only after the team-profile gate passes. Map by relevant capability,
+capacity, ownership, and support needs, not title or headcount. Ensure owners do
+not approve their own changes. Name an integration owner only for milestones
+that cross ownership boundaries.
+
+Treat review capacity as real work. Confirm reviewer availability before an item
+becomes ready and define a small review queue limit (default two active reviews
+per reviewer unless the team chooses otherwise). For high- or critical-risk
+work, separately name any policy-authorized security, privacy, compliance, or
+operations approver; never assume an ordinary code reviewer has that authority.
+
+Track changing assignments, availability, and status in the existing project
+tracker. Do not version them as architecture.
+
+## 5. Check readiness
+
+An item is ready only when its outcome, acceptance, required design decisions,
+dependencies, owner, reviewer, and test environment are known. Use a bounded
+discovery item when evidence is missing. Never disguise uncertainty as an
+implementation task.
+
+Do not assign an item merely because there are idle developers. Keep it
+unassigned or blocked until its contract, owner, and independent reviewer are
+known. If the plan is still awaiting team profiles, report it as an unassigned
+planning brief rather than a ready delivery plan.
+
+Review the plan with the team in one pass: current milestone, ready work,
+parallel work, blockers, integration points, and risks. Update routine status
+without formal approval; seek human decisions only for scope, priority, risk,
+ownership conflicts, or commitments.
+
+## Handoff
+
+Give each developer only their work item, relevant brief/design/API links,
+integration constraints, and acceptance criteria. Start `build-change` for the
+next ready item.

codev_workflow/bundle/.agents/skills/plan-delivery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan Delivery"
+  short_description: "Plan milestones, owners, dependencies, and risks"
+  default_prompt: "Use $plan-delivery to turn this accepted brief and design into a lightweight team delivery plan."

codev_workflow/bundle/.agents/skills/plan-delivery/assets/delivery-plan.template.md

@@ -0,0 +1,41 @@
+# [Product or Feature] Delivery Plan
+
+**Status:** Active
+**Owner:** [delivery owner]
+**Brief:** [link]
+**Design:** [link or Not needed]
+**Last reviewed:** [YYYY-MM-DD]
+
+## Current milestone
+
+**Outcome:** [Demonstrable user/system outcome]
+**Evidence:** [How the team will prove it]
+**Target:** [Date/range or Not committed]
+
+## Current work
+
+| ID | Work item and acceptance | Owner | Reviewer | Risk | Status | Blocked by | Integrates with / lands after | Validation |
+|---|---|---|---|---|---|---|---|---|
+| W-01 | [bounded outcome] | [owner] | [reviewer] | [level] | Ready | — | [relation] | [checks] |
+
+## Integration checkpoints
+
+| Checkpoint | Participating work | Owner | Entry evidence | Completion evidence |
+|---|---|---|---|---|
+| [checkpoint] | [IDs] | [owner] | [conditions] | [test/demo] |
+
+## Risks and discovery
+
+| Risk or unknown | Impact | Evidence-producing action | Owner | Decision point |
+|---|---|---|---|---|
+| [risk] | [impact] | [action] | [owner] | [when] |
+
+## Later milestones
+
+- **[Outcome]:** [coarse scope; refine after current evidence]
+
+## Team agreements
+
+- Default implementation WIP: one item per developer.
+- Owners do not approve their own changes.
+- Status and availability live here or in the linked project tracker, not in architecture documents.

codev_workflow/bundle/.agents/skills/review-change/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: review-change
+description: Independently review a pull request, commit, patch, or working-tree diff for correctness, regressions, security, test quality, maintainability, scope, and conformance to an accepted brief or design. Use when a developer requests code review, a second AI pass, pre-merge assurance, or an evidence-based quality gate. Review only the exact supplied snapshot and do not modify code unless explicitly asked afterward.
+---
+
+# Review Change
+
+Act as an independent reviewer, not a second implementer. Review the exact
+base-to-head snapshot and state the snapshot when possible.
+
+## Preconditions
+
+Read the issue or work item, acceptance criteria, relevant brief/design/API,
+repository instructions, complete diff, and validation evidence. Inspect enough
+surrounding code to understand behavior. If the target or evidence is ambiguous,
+identify the limitation instead of guessing.
+
+## Review order
+
+Prioritize:
+
+1. incorrect or missing required behavior;
+2. security, privacy, permission, data-loss, concurrency, and compatibility risk;
+3. error handling and edge cases;
+4. test quality, missing tests, and weakened or misleading tests;
+5. architecture/API conformance and unnecessary scope;
+6. maintainability, clarity, documentation, and repository conventions; and
+7. rollout, monitoring, migration, and rollback concerns.
+
+Passing checks are evidence, not proof. Rerun proportionate checks when useful
+and authorized. Do not invent requirements or block on personal style.
+
+## Findings
+
+Lead with actionable findings, ordered by severity:
+
+- **P0:** immediate security, data-loss, or production-critical defect.
+- **P1:** incorrect behavior or likely serious regression; blocks merge.
+- **P2:** material maintainability, test, or edge-case problem; normally fix.
+- **P3:** optional improvement; never disguise it as a blocker.
+
+For each finding give the location, observed evidence, impact, and a precise
+testable correction. Keep line ranges tight. If no actionable finding exists,
+say so and list residual risks or validation gaps.
+
+End with one recommendation: `READY FOR HUMAN APPROVAL`, `CHANGES REQUIRED`, or
+`BLOCKED BY MISSING EVIDENCE`. Reviewer readiness never authorizes merge or
+release.

codev_workflow/bundle/.agents/skills/review-change/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review Change"
+  short_description: "Review a change for correctness, risk, and quality"
+  default_prompt: "Use $review-change to independently review this exact change and its validation evidence."

codev_workflow/bundle/.agents/skills/specify-project/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: specify-project
+description: Interview a developer one question at a time to create or revise a canonical SPECIFICATION.md that combines an accepted product frame with a high-level technical blueprint. Use for a new greenfield product, a whole-product redesign, or an explicit request for a comprehensive project specification. Do not use for a bounded feature, implementation plan, roadmap, task breakdown, or code change.
+---
+
+# Specify Project
+
+Guide a developer through one continuous, recommendation-led interview while
+preserving two internal decisions: first accept the product frame, then accept
+the technical design. Produce one canonical `SPECIFICATION.md`; do not also copy
+the same facts into a separate brief and design.
+
+Read `references/interview-coverage.md` completely before beginning the
+interview. Read `assets/specification.template.md` completely before creating or
+revising the artifact.
+
+## 1. Confirm this is the right path
+
+Use this skill for a new product or whole-system blueprint where the user wants
+a thorough guided interview and one combined specification.
+
+Redirect instead when:
+
+- a bounded brownfield feature needs `define-product` and, if material,
+  `design-solution`;
+- a local fix or refactor can start with `build-change`;
+- an accepted specification needs milestones and work items from
+  `plan-delivery`; or
+- the request is to implement code.
+
+Risk overrides apparent size. Do not use the combined format to avoid required
+security, privacy, data, reliability, accessibility, or domain review.
+
+## 2. Establish the working context
+
+Read all supplied source material. If a repository exists, inspect its
+instructions, current architecture, code, interfaces, schemas, tests, build,
+deployment, ownership, and prior decisions before asking technical questions.
+Do not ask the developer for discoverable repository facts.
+
+Choose one canonical artifact location:
+
+- single-product repository: `SPECIFICATION.md` at the repository root;
+- monorepo or multi-product repository:
+  `docs/product/<slug>/SPECIFICATION.md`; or
+- an established repository convention when one already exists.
+
+State the proposed location early. Do not overwrite an unrelated specification.
+Use Git as revision history; do not invent document revision identifiers.
+
+Maintain a decision ledger during the interview with four categories:
+
+- **Verified:** supported by repository or authoritative evidence;
+- **Decision:** explicitly accepted by the responsible human;
+- **Assumption:** plausible but not yet supported;
+- **Open:** unresolved and either blocking or non-blocking.
+
+## 3. Follow the interview contract
+
+During discovery, ask exactly one targeted question per response. End the
+response with one interrogative sentence and avoid other question marks.
+
+Use this response shape:
+
+```markdown
+**Current understanding:** [one short synthesis]
+
+**Recommendation:** [one concrete default and why]
+
+**Trade-offs:** [only for a material choice; two or three real alternatives]
+
+**Question:** [exactly one question]
+```
+
+Apply these rules:
+
+- Ask the highest-impact unresolved question, not a fixed questionnaire.
+- Include a recommendation the developer can accept with "yes".
+- Ground the recommendation in known constraints and label uncertainty.
+- Challenge vague, contradictory, unsafe, or non-viable answers respectfully.
+- Do not invent users, evidence, numerical targets, scale, policy, or constraints.
+- Do not force irrelevant topics, technologies, agents, services, or APIs into
+  the design.
+- Answer a user's side question before continuing with one next interview
+  question.
+- Briefly summarize progress every five to eight answers without adding another
+  question.
+- Revisit an accepted decision only when new evidence creates a material conflict.
+
+The one-question rule governs the interview, not the final artifact handoff or a
+requested read-only status summary.
+
+## 4. Accept the product frame first
+
+Establish the product half before selecting architecture:
+
+- problem, evidence, target users, and affected stakeholders;
+- desired outcome, measures, guardrails, and baseline plan;
+- essential user and failure scenarios;
+- first-release scope, explicit non-goals, and plausible later work;
+- business, legal, safety, privacy, accessibility, platform, cost, and timing
+  constraints; and
+- assumptions that need evidence.
+
+Prefer a bounded discovery experiment if the central user, problem, or outcome
+is not supported. Never turn a proposed technology into the product problem.
+
+When the product frame is coherent, summarize it, recommend acceptance, and ask
+the human for one explicit acceptance decision. Record `Product frame: Accepted`
+only after confirmation. Do not begin detailed architecture while a blocking
+product decision remains open.
+
+## 5. Design the high-level system
+
+After product-frame acceptance, settle only technical decisions that must be
+shared before delivery planning or parallel implementation. Cover applicable
+areas from `references/interview-coverage.md`, including:
+
+- system context, components, responsibilities, ownership, and dependencies;
+- domain model, state transitions, data lifecycle, schemas, and auditability;
+- public and internal contracts, clients, protocols, errors, and compatibility;
+- trust boundaries, identity, permissions, privacy, abuse, and secrets;
+- failure isolation, timeouts, retries, idempotency, recovery, and degradation;
+- concurrency, capacity, performance, availability, and cost;
+- configuration, environments, deployment topology, and operations;
+- observability, test/evaluation strategy, migration, rollout, rollback, and
+  cleanup; and
+- credible alternatives and consequences.
+
+For each cross-component contract define its owner, consumers, behavior,
+validation, errors/timeouts, compatibility, and contract evidence. Do not
+prescribe private classes, file layouts, algorithms, sprint work, or code unless
+they are genuinely part of the external architectural contract.
+
+Use text, ASCII, or Mermaid diagrams according to repository convention. Explain
+the important paths and boundaries in prose; a diagram is not a specification by
+itself.
+
+## 6. Determine completeness honestly
+
+Do not claim that every possible unknown is resolved. The specification is ready
+for acceptance only when:
+
+- the product outcome, V1 scope, and non-goals are accepted;
+- interfaces, data, ownership, security, failure behavior, and deployment are
+  precise enough for delivery planning;
+- acceptance scenarios trace to components, contracts, tests, and rollout
+  evidence;
+- no open decision blocks safe planning;
+- every remaining non-blocking unknown has an owner, evidence-producing action,
+  and decision point; and
+- required domain reviewers are named.
+
+Run a consistency pass before acceptance. Identify contradictions, unsupported
+claims, orphan components, unowned contracts, untestable requirements, unsafe
+migrations, and rollback paths that cannot restore a supported state.
+
+## 7. Create and accept `SPECIFICATION.md`
+
+Use `assets/specification.template.md`. Adapt headings only when a section is
+genuinely inapplicable; say why rather than silently omitting a production
+concern.
+
+Set the document and both checkpoints to `Draft` initially. Mark the product
+frame and technical design separately as `Accepted` after their human decisions.
+Set the document `Status: Accepted` only when both checkpoints are accepted,
+blocking decisions are closed, required reviews are complete, and the accountable
+human approves planning against the exact file.
+
+For a substantive specification, run:
+
+```bash
+python .agents/skills/specify-project/scripts/validate_specification.py <path>
+```
+
+The validator checks structure, not architectural correctness. Report its exact
+result and any limitations.
+
+## 8. Handoff without implementation planning
+
+Conclude with:
+
+- artifact path and status;
+- accepted product and technical checkpoints;
+- important decisions and non-blocking unknowns;
+- required follow-up evidence and domain reviews; and
+- the recommended next action.
+
+For multi-developer or multi-milestone work, hand the accepted specification to
+`plan-delivery`. For a single bounded first slice, hand it to `build-change`.
+Do not generate a roadmap, sprint plan, staffing allocation, task checklist, or
+code while using this skill.
+
+## Stop conditions
+
+Stop with verified facts, a recommendation, and one precise question when:
+
+- product answers conflict or the central outcome lacks evidence;
+- a material API, data, security, cost, ownership, or architecture decision has
+  no accountable human;
+- the repository contradicts the proposed design;
+- required specialist input is unavailable;
+- the specification would describe an unsafe or unverifiable system; or
+- the user asks to proceed to implementation before the required acceptance
+  checkpoint.

codev_workflow/bundle/.agents/skills/specify-project/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Specify Project"
+  short_description: "Interview and create a project specification"
+  default_prompt: "Use $specify-project to interview me one question at a time and create an accepted SPECIFICATION.md."

codev_workflow/bundle/.agents/skills/specify-project/assets/specification.template.md

@@ -0,0 +1,151 @@
+# [Project Name] Specification
+
+**Status:** Draft
+**Product frame:** Draft
+**Technical design:** Draft
+**Product owner:** [name or team]
+**Technical owner:** [name or team]
+**Required reviewers:** [technical and specialist reviewers]
+**Last reviewed:** [YYYY-MM-DD]
+
+## Executive summary
+
+<!-- State the user problem, intended outcome, and recommended system in plain language. -->
+
+## Problem, users, and evidence
+
+<!-- Identify users, current problem, supporting evidence, and affected stakeholders. -->
+
+## Product vision and desired outcomes
+
+<!-- Describe changed user or system behavior, not shipped components. -->
+
+## Success measures and guardrails
+
+| Measure | Baseline or baseline plan | Target/decision rule | Window | Source | Owner |
+|---|---|---|---|---|---|
+| [measure] | [baseline] | [target] | [window] | [source] | [owner] |
+
+## Essential scenarios
+
+- <!-- Primary end-to-end user behavior. -->
+- <!-- Important failure, denial, or recovery behavior. -->
+
+## V1 scope
+
+### Included
+
+- <!-- Smallest complete first-release outcome. -->
+
+### Later possibilities
+
+- <!-- Plausible follow-up; not committed. -->
+
+## Non-goals
+
+- <!-- Explicitly excluded behavior, client, abstraction, or operational promise. -->
+
+## Constraints
+
+- <!-- Business, legal, safety, privacy, accessibility, platform, cost, or timing constraint. -->
+
+## Assumptions and unresolved questions
+
+| Item | Classification | Blocking | Owner | Evidence/action | Decision point |
+|---|---|---|---|---|---|
+| [item] | [assumption/open] | [yes/no] | [owner] | [evidence] | [point] |
+
+## Architectural context
+
+<!-- Describe existing systems, external actors, constraints, and verified sources. -->
+
+## System architecture
+
+<!-- Show the major components and important data/control flows using text, ASCII, or Mermaid. -->
+
+## Components and ownership
+
+| Component | Responsibility | Owner | Inputs | Outputs | Dependencies |
+|---|---|---|---|---|---|
+| [component] | [responsibility] | [owner] | [inputs] | [outputs] | [dependencies] |
+
+## Domain model and state transitions
+
+<!-- Define important entities/value types, invariants, relationships, lifecycle, and transitions. -->
+
+## Data lifecycle and retention
+
+<!-- Define creation, validation, storage, classification, access, audit, retention, export, and deletion. -->
+
+## APIs, protocols, and contracts
+
+| Contract | Owner | Consumers | Shape/reference | Guarantees | Validation/errors/timeouts | Compatibility | Test/fixture |
+|---|---|---|---|---|---|---|---|
+| [contract] | [owner] | [consumers] | [shape] | [guarantees] | [behavior] | [policy] | [evidence] |
+
+## Supported clients and interfaces
+
+<!-- Specify applicable web, mobile, desktop, CLI, API, event, tool, or AI interfaces. -->
+
+## Component orchestration rules
+
+<!-- Define sequencing, isolation, coordination, authority, cancellation, and duplicate handling. -->
+
+## Security, privacy, and abuse controls
+
+<!-- Define trust boundaries, identity, permissions, input/output handling, secrets, sensitive data, and abuse controls. -->
+
+## Failure modes and resilience
+
+| Failure | User/system effect | Detection | Containment/fallback | Recovery | Owner |
+|---|---|---|---|---|---|
+| [failure] | [effect] | [signal] | [behavior] | [recovery] | [owner] |
+
+## Concurrency, capacity, performance, and cost
+
+<!-- Define only justified limits, targets, resource bounds, and scale assumptions. -->
+
+## Configuration and deployment topology
+
+<!-- Define configuration precedence, secrets, environments, processes/containers, state, regions, and dependencies. -->
+
+## Observability and operations
+
+<!-- Define logs, metrics, traces, dashboards, alerts, SLOs, support/on-call, backup, restore, and runbooks. -->
+
+## Test and evaluation strategy
+
+<!-- Trace unit, contract, integration, end-to-end, performance, resilience, security, and acceptance evidence. -->
+
+## Compatibility and migration
+
+<!-- Define schema/API versioning, old/new coexistence, migration ordering, validation, and cleanup. -->
+
+## Rollout, rollback, and cleanup
+
+<!-- Define flags, stages, success/guardrail thresholds, observation, rollback, and temporary-code removal. -->
+
+## Alternatives and trade-offs
+
+| Option | Benefits | Costs/risks | Decision and evidence |
+|---|---|---|---|
+| [option] | [benefits] | [costs] | [chosen/rejected and why] |
+
+## Risks and open decisions
+
+| Risk/decision | Impact | Blocking | Owner | Mitigation/evidence | Due/decision point |
+|---|---|---|---|---|---|
+| [risk] | [impact] | [yes/no] | [owner] | [action] | [point] |
+
+## Source references
+
+- <!-- Link canonical product evidence, repository facts, policies, designs, or external standards. -->
+
+## Acceptance
+
+- [ ] Product frame accepted by the accountable product owner.
+- [ ] Material technical decisions resolved.
+- [ ] Required technical and specialist reviews complete.
+- [ ] No blocking unknown or decision remains.
+- [ ] Acceptance scenarios trace to contracts, tests, and rollout evidence.
+- [ ] Accountable human accepts delivery planning against this specification.