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

codev_workflow/bundle/.agents/skills/specify-project/references/interview-coverage.md

@@ -0,0 +1,303 @@
+# Project Specification Interview Coverage
+
+Use this reference as a coverage map, not a questionnaire. Ask only the
+highest-impact unresolved question and skip topics that are demonstrably
+inapplicable. Every recommendation must be grounded in accepted context.
+
+## Contents
+
+1. Product frame
+2. Domain and lifecycle
+3. System boundaries and ownership
+4. Interfaces and contracts
+5. Data
+6. Security, privacy, and abuse
+7. Failure and resilience
+8. Concurrency, scale, performance, and cost
+9. Clients and human interfaces
+10. AI, agents, and tool use
+11. Configuration and deployment
+12. Observability and operations
+13. Testing and evaluation
+14. Compatibility, migration, and release
+15. Completeness and consistency
+
+## 1. Product frame
+
+Establish:
+
+- the primary user and the situation in which the problem occurs;
+- evidence that the problem exists, its frequency, and current workaround;
+- affected users, administrators, operators, and non-users;
+- the desired change in behavior or system state;
+- leading measures, durable outcomes, guardrails, baseline plan, and owner;
+- primary success, denial, degraded, and recovery scenarios;
+- the smallest complete V1 outcome;
+- explicit non-goals and later possibilities;
+- fixed legal, policy, accessibility, platform, cost, and timing constraints;
+- assumptions whose failure would invalidate the project.
+
+Recommend a discovery experiment instead of architecture when the central user,
+problem, or outcome remains speculative. Never invent numerical targets.
+
+## 2. Domain and lifecycle
+
+Identify only concepts with architectural consequences:
+
+- core entities, value types, identities, and invariants;
+- ownership and authoritative source for each concept;
+- valid states and transitions;
+- commands, events, and side effects that cause transitions;
+- uniqueness, ordering, temporal, and consistency rules;
+- creation, activation, suspension, expiry, deletion, and restoration;
+- audit or historical reconstruction requirements;
+- human override and exceptional-state behavior.
+
+Prefer domain language used by actual users. Do not convert every noun into a
+class or database table.
+
+## 3. System boundaries and ownership
+
+Determine:
+
+- external actors and systems;
+- major components and one responsibility for each;
+- existing capability to reuse rather than recreate;
+- component and interface owners;
+- dependency direction and prohibited dependencies;
+- synchronous and asynchronous control flow;
+- source of truth and cache/materialized-view boundaries;
+- trust, deployment, failure, and scaling boundaries;
+- isolation between users, tenants, workloads, or plugins;
+- decisions local implementers may make independently.
+
+Every component must contribute to an accepted scenario. Remove orphan
+components and abstractions without a demonstrated responsibility.
+
+## 4. Interfaces and contracts
+
+For each human or machine interface establish:
+
+- owner, consumers, purpose, and stability promise;
+- protocol and authoritative schema location;
+- operation, request/event/resource shape, and response/result;
+- validation and normalization;
+- authentication and authorization context;
+- error taxonomy and retryability;
+- timeout, cancellation, pagination, streaming, and size limits;
+- idempotency, ordering, deduplication, and concurrency behavior;
+- compatibility, versioning, deprecation, and removal;
+- rate limits and quota semantics;
+- contract fixtures or tests.
+
+Specify semantics rather than private implementation. Use REST, gRPC, events,
+MCP, GraphQL, CLI commands, or another protocol only when context supports it.
+
+## 5. Data
+
+Cover applicable lifecycle stages:
+
+- collection or creation and lawful purpose;
+- validation and canonical representation;
+- classification and sensitive fields;
+- storage technology constraints and authoritative copy;
+- indexes, relationships, consistency, and transaction boundaries;
+- encryption, key ownership, and access control;
+- audit, lineage, provenance, and change history;
+- backup, restore, export, portability, and legal hold;
+- retention, expiry, deletion, and deletion propagation;
+- residency and cross-region/cross-tenant constraints;
+- schema evolution, migration, and old-reader/new-writer compatibility;
+- test-data strategy and prohibition on uncontrolled production data.
+
+Do not select a datastore until access patterns, consistency, lifecycle, and
+operational ownership justify it.
+
+## 6. Security, privacy, and abuse
+
+Identify:
+
+- assets, actors, trust boundaries, and attacker capabilities;
+- identity source and session or workload identity lifecycle;
+- authorization decisions and least-privilege roles;
+- untrusted input and destination-specific output handling;
+- secret storage, delivery, rotation, revocation, and audit;
+- personal or regulated data purpose, minimization, consent, and retention;
+- tenant isolation and confused-deputy risks;
+- administrative and emergency access;
+- abuse, enumeration, scraping, denial-of-service, and fraud controls;
+- dependency and build supply-chain protections;
+- security event evidence and private reporting/incident ownership.
+
+Escalate material choices to the appropriate specialist. Do not interpret
+absence of a stated regulation as permission to collect data.
+
+## 7. Failure and resilience
+
+For each important dependency or operation establish:
+
+- expected local and downstream failures;
+- visible user behavior under failure;
+- timeout and cancellation propagation;
+- retry eligibility, limit, backoff, and jitter;
+- idempotency and duplicate handling;
+- circuit breaking, load shedding, or queue backpressure;
+- fault containment and blast radius;
+- degraded but supported modes;
+- detection and diagnostic evidence;
+- automatic versus human recovery;
+- recovery point and recovery time expectations;
+- rollback or forward-repair path.
+
+Retries are not a default. They can amplify overload or duplicate non-idempotent
+work.
+
+## 8. Concurrency, scale, performance, and cost
+
+Seek evidence for:
+
+- expected and peak users, requests, events, or data volume;
+- latency and throughput expectations tied to a user outcome;
+- concurrency model, contention points, and ordering requirements;
+- queue, connection, thread/process, memory, storage, and payload bounds;
+- admission control, quotas, and noisy-neighbor protection;
+- horizontal or vertical scaling boundaries;
+- load, stress, endurance, and capacity evaluation;
+- infrastructure, third-party, model, storage, egress, and support cost;
+- cost limits, measurement, and owner.
+
+When no baseline exists, specify how to establish it. Do not invent internet
+scale for a small internal tool.
+
+## 9. Clients and human interfaces
+
+For applicable web, mobile, desktop, CLI, API, or assistive clients cover:
+
+- supported clients, platforms, versions, and ownership;
+- primary journeys and recovery behavior;
+- client/server responsibility and offline behavior;
+- accessibility, keyboard, screen-reader, contrast, and reduced-motion needs;
+- localization, time zones, currencies, units, and text expansion;
+- authentication, session expiry, and permission-denied experience;
+- optimistic updates, conflict handling, and stale data;
+- client compatibility and update policy;
+- telemetry and privacy-respecting user feedback.
+
+Do not make a UI framework an architectural requirement without a client and
+maintenance reason.
+
+## 10. AI, agents, and tool use
+
+Use this section only when the product contains an AI capability. Establish:
+
+- model purpose and behavior that remains deterministic outside the model;
+- model/provider/version selection and change policy;
+- prompt, retrieval corpus, context, and memory ownership;
+- data use, retention, residency, and training restrictions;
+- model-output validation and safe fallback;
+- prompt injection and untrusted-content boundaries;
+- allowed tools and per-tool permission scope;
+- human authorization for consequential actions;
+- isolation between agents, users, and tenants;
+- maximum steps, time, tokens, cost, retries, and cancellation;
+- offline evaluation set, provenance, owner, and contamination control;
+- quality, safety, latency, availability, and cost thresholds;
+- monitoring for drift, regressions, abuse, and unexpected tool use;
+- rollback across prompt, model, tools, retrieval data, and application versions.
+
+Never specify "the model decides" where a stable contract, authorization rule,
+or safety invariant is required.
+
+## 11. Configuration and deployment
+
+Determine:
+
+- runtime and supported platform versions;
+- processes, containers, functions, jobs, or device topology;
+- environment boundaries and promotion flow;
+- configuration schema, source precedence, validation, and versioning;
+- secret and workload-identity delivery;
+- stateful and stateless boundaries;
+- network ingress, egress, service discovery, and trust boundaries;
+- regional, availability-zone, residency, or edge requirements;
+- deployment ownership and least-privilege automation;
+- immutable artifact identity and provenance;
+- infrastructure creation, update, drift, and deletion;
+- local development and representative preproduction topology.
+
+Separate required properties from a vendor choice unless organizational policy
+already fixes the provider.
+
+## 12. Observability and operations
+
+Define:
+
+- product, correctness, security, reliability, and cost signals;
+- structured logs and correlation without sensitive payloads;
+- metrics, traces, dashboards, and actionable alerts;
+- service-level indicators, objectives, and error-budget response when relevant;
+- health, readiness, dependency, queue, and saturation signals;
+- on-call or support ownership and escalation route;
+- runbooks for common and dangerous failure modes;
+- backup/restore, disaster recovery, and operational drills;
+- incident evidence, communication, and post-incident learning;
+- dependency maintenance, deprecation, and end-of-life ownership.
+
+Every signal needs a decision or operational action. Avoid telemetry collected
+without an owner or purpose.
+
+## 13. Testing and evaluation
+
+Trace accepted scenarios and risks to:
+
+- unit evidence for deterministic rules;
+- contract evidence for shared interfaces;
+- integration evidence for real adapters and infrastructure;
+- end-to-end evidence for critical user journeys;
+- negative authorization, abuse, and validation cases;
+- migration, compatibility, and rollback tests;
+- performance, capacity, resilience, and restore evaluation;
+- accessibility and internationalization evidence;
+- evaluator ownership and independence;
+- test-data boundaries and flake control;
+- release-candidate and production verification.
+
+For critical or AI-generated behavior, protect evaluation integrity with
+independent, immutable, hidden, property-based, fuzz, mutation, or differential
+tests as appropriate. Passing visible tests is not complete evidence.
+
+## 14. Compatibility, migration, and release
+
+Establish:
+
+- supported old and new clients, readers, writers, and artifacts;
+- additive or breaking contract changes;
+- expand/migrate/contract ordering;
+- backfill, dual-read/write, validation, and reconciliation;
+- feature-flag ownership and safe default;
+- internal, staging, shadow, canary, and broader cohorts;
+- product and reliability success thresholds;
+- guardrails, observation duration, stop conditions, and decision owner;
+- rollback to a supported data and code state;
+- cleanup of flags, compatibility paths, temporary infrastructure, and data;
+- user, operator, support, and developer communication.
+
+Do not include sprint sequencing or work assignment. This section specifies safe
+states and release constraints for later delivery planning.
+
+## 15. Completeness and consistency
+
+Before recommending technical-design acceptance, verify:
+
+- each V1 scenario has an owning component and contract path;
+- each external dependency has failure and operational behavior;
+- each sensitive data flow crosses identified trust boundaries safely;
+- each state transition has authority, validation, and recovery;
+- each shared interface has one owner and compatibility policy;
+- each material claim has evidence or is labeled an assumption;
+- each accepted quality target has test or production evidence;
+- each migration step preserves a supported intermediate state;
+- rollback does not depend on an irreversible schema or data change;
+- every open item is classified as blocking or non-blocking;
+- every non-blocking item has an owner and decision point;
+- the specification contains no implementation roadmap or task checklist.

codev_workflow/bundle/.agents/skills/specify-project/scripts/validate_specification.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Validate the structure and acceptance state of a project specification."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+REQUIRED_METADATA = (
+    "Status",
+    "Product frame",
+    "Technical design",
+    "Product owner",
+    "Technical owner",
+    "Required reviewers",
+    "Last reviewed",
+)
+
+REQUIRED_SECTIONS = (
+    "Executive summary",
+    "Problem, users, and evidence",
+    "Product vision and desired outcomes",
+    "Success measures and guardrails",
+    "Essential scenarios",
+    "V1 scope",
+    "Non-goals",
+    "Constraints",
+    "Assumptions and unresolved questions",
+    "Architectural context",
+    "System architecture",
+    "Components and ownership",
+    "Domain model and state transitions",
+    "Data lifecycle and retention",
+    "APIs, protocols, and contracts",
+    "Supported clients and interfaces",
+    "Component orchestration rules",
+    "Security, privacy, and abuse controls",
+    "Failure modes and resilience",
+    "Concurrency, capacity, performance, and cost",
+    "Configuration and deployment topology",
+    "Observability and operations",
+    "Test and evaluation strategy",
+    "Compatibility and migration",
+    "Rollout, rollback, and cleanup",
+    "Alternatives and trade-offs",
+    "Risks and open decisions",
+    "Source references",
+    "Acceptance",
+)
+
+ALLOWED_STATES = {"Draft", "Accepted", "Superseded"}
+PLACEHOLDER = re.compile(
+    r"\b(?:TODO|TBD)\b|<!--|"
+    r"\[(?:Project Name|name or team|technical and specialist reviewers|"
+    r"YYYY-MM-DD|measure|baseline|target|window|source|owner|item|"
+    r"assumption/open|yes/no|evidence|point|component|responsibility|inputs|"
+    r"outputs|dependencies|contract|consumers|shape|guarantees|behavior|policy|"
+    r"failure|effect|signal|recovery|option|benefits|costs|"
+    r"chosen/rejected and why|risk|impact|action)\](?!\()",
+    re.IGNORECASE,
+)
+
+
+def metadata(text: str, field: str) -> str | None:
+    match = re.search(
+        rf"^\*\*{re.escape(field)}:\*\*\s*(.*?)\s*$",
+        text,
+        re.MULTILINE,
+    )
+    return match.group(1) if match else None
+
+
+def validate(path: Path) -> list[str]:
+    errors: list[str] = []
+    if not path.is_file():
+        return [f"{path}: file does not exist"]
+
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    if not lines or not re.fullmatch(r"#\s+.+\s+Specification", lines[0]):
+        errors.append("first line must be '# <Project Name> Specification'")
+
+    values: dict[str, str] = {}
+    for field in REQUIRED_METADATA:
+        value = metadata(text, field)
+        if value is None:
+            errors.append(f"missing metadata field: {field}")
+        else:
+            values[field] = value
+
+    for field in ("Status", "Product frame", "Technical design"):
+        value = values.get(field)
+        if value is not None and value not in ALLOWED_STATES:
+            errors.append(f"{field} must be Draft, Accepted, or Superseded")
+
+    headings = {
+        match.group(1).strip()
+        for match in re.finditer(r"^##\s+(.+?)\s*$", text, re.MULTILINE)
+    }
+    for section in REQUIRED_SECTIONS:
+        if section not in headings:
+            errors.append(f"missing section: {section}")
+
+    if values.get("Status") == "Accepted":
+        if values.get("Product frame") != "Accepted":
+            errors.append("accepted document requires an accepted product frame")
+        if values.get("Technical design") != "Accepted":
+            errors.append("accepted document requires an accepted technical design")
+        if PLACEHOLDER.search(text):
+            errors.append("accepted document contains a placeholder or HTML comment")
+        unchecked = re.findall(r"^- \[ \]", text, re.MULTILINE)
+        if unchecked:
+            errors.append("accepted document contains unchecked acceptance criteria")
+        for field in ("Product owner", "Technical owner", "Required reviewers"):
+            value = values.get(field, "")
+            if not value or value.casefold() in {"none", "n/a", "unknown"}:
+                errors.append(f"accepted document requires {field}")
+
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("specification", type=Path)
+    args = parser.parse_args()
+
+    errors = validate(args.specification)
+    if errors:
+        print(f"Specification validation failed: {args.specification}")
+        for error in errors:
+            print(f"- {error}")
+        return 1
+
+    state = metadata(args.specification.read_text(encoding="utf-8"), "Status")
+    print(f"Specification validation passed ({state}): {args.specification}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codev_workflow/bundle/.opencode/agents/builder.md

@@ -0,0 +1,54 @@
+---
+description: Bounded implementation subagent that executes one accepted work-item plan
+mode: subagent
+permission:
+  edit: allow
+  task: deny
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "git log*": allow
+    "git show*": allow
+    "git rev-parse*": allow
+    "git commit*": deny
+    "git push*": deny
+  external_directory: deny
+---
+
+Implement exactly one bounded work item delegated by the orchestrator. Follow
+`AGENTS.md`, `docs/for-ai/WORKFLOW-AGENTS.md`, and `build-change`. Treat the
+accepted implementation plan and its cited brief/specification/design/API as
+authority; do not redesign them to make coding easier.
+
+Before editing:
+
+1. inspect the actual files, symbols, tests, build commands, conventions, Git
+   state, and nearby comparable implementation;
+2. verify the base snapshot and check for unrelated or concurrent changes;
+3. compare repository facts with the accepted plan; and
+4. return `BLOCKED` with exact evidence when a material mismatch, missing
+   decision, scope expansion, collision, or unavailable validation prevents safe
+   execution. Do not invent the missing answer.
+
+When ready, implement the smallest coherent review purpose. Stay within allowed
+scope, reuse repository patterns, put tests with behavior, and avoid unrelated
+cleanup. Never weaken tests, silently change contracts, add unaccepted
+dependencies, or modify accepted planning artifacts. Keep the repository
+buildable and stop after two failed attempts with the same root cause.
+
+Run the specified formatter, static checks, affected tests, and proportionate
+broader validation. Inspect the complete diff. Return only observable handoff
+information:
+
+- **Delivered:** outcome and behavior;
+- **Changed:** files and components;
+- **Base/head snapshot:** exact values;
+- **Validation actually run:** commands and outcomes;
+- **Acceptance evidence:** criterion mapped to evidence;
+- **Scope deviations:** none or explicitly accepted deviations;
+- **Known limitations:** risks and follow-up; and
+- **Review state:** `AWAITING INDEPENDENT REVIEW`.
+
+Do not invoke another agent, approve the change, commit, push, merge, publish,
+deploy, migrate data, or expand rollout.

codev_workflow/bundle/.opencode/agents/orchestrator.md

@@ -0,0 +1,72 @@
+---
+description: Human-controlled workflow orchestrator for planning, delegated building, and independent review
+mode: primary
+permission:
+  edit: ask
+  task:
+    "*": deny
+    builder: allow
+    reviewer: allow
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "git log*": allow
+    "git show*": allow
+    "git rev-parse*": allow
+    "git commit*": deny
+    "git push*": deny
+  external_directory: deny
+---
+
+Act as the human's primary engineering partner. Follow `AGENTS.md`,
+`docs/for-ai/WORKFLOW-AGENTS.md`, and the applicable repository skills. Present
+the work as `Understand`, `Build`, `Review`, or `Ship` and select the lightest
+safe path without requiring the human to know skill names.
+
+For Understand and Ship work, use the applicable lifecycle skill directly.
+Create or revise planning artifacts only when the selected skill requires them
+and the human has authorized the write. Never implement product code while
+acting as orchestrator.
+
+## Three-agent Build protocol
+
+For one ready work item:
+
+1. Read the work item, upstream brief/specification/design/API authority,
+   repository instructions, current code and tests, ownership, and Git state.
+2. Confirm the item is ready. Return unresolved product questions to
+   `define-product`, architectural or contract questions to `design-solution`,
+   and dependency or assignment problems to `plan-delivery`.
+3. Use `build-change` to frame and ground the change. Present the focus card.
+   For delegated, multi-session, cross-component, normal-risk, or higher-risk
+   work, render the complete
+   `.agents/skills/build-change/assets/implementation-plan.template.md` in the
+   conversation. Do not ask the human to write it.
+4. Obtain one precise human decision for any material product, API, data,
+   dependency, architecture, security, destructive, scope, or risk choice. Ask
+   for approval before starting delegated implementation. Do not delegate an
+   unresolved or unaccepted plan.
+5. Invoke `builder` with the accepted work item and implementation plan, exact
+   authority links, base commit, allowed scope, integration constraints,
+   validation, and stop conditions. Pass task-local artifacts, not private
+   reasoning or a broad conversation transcript.
+6. When the builder returns, verify that its evidence receipt identifies an
+   exact head snapshot, actual validation, deviations, limitations, and changed
+   files. If evidence is missing, return the task for evidence rather than
+   guessing.
+7. Invoke `reviewer` in a fresh task with the exact base-to-head snapshot, work
+   item, accepted plan, upstream authority, and builder evidence receipt.
+8. If the reviewer returns actionable findings, send the findings and original
+   accepted plan back to `builder`. Do not let the reviewer edit. Repeat review
+   after correction. After two correction attempts with the same root cause,
+   or whenever the accepted plan must change materially, stop for the human
+   with evidence and a recommendation.
+9. Return the final evidence receipt, reviewer decision, residual risks, and
+   exact snapshot. Never claim approval and stop before commit, merge, publish,
+   deploy, migration, or rollout expansion unless the human explicitly grants
+   the corresponding authority.
+
+Keep progress visible at plan acceptance, builder completion, reviewer result,
+and any stop condition. Do not spawn unrelated agents or parallel builders in
+the same worktree.

codev_workflow/bundle/.opencode/agents/reviewer.md

@@ -0,0 +1,35 @@
+---
+description: Independent reviewer for one exact code change
+mode: subagent
+permission:
+  edit: deny
+  task: deny
+  bash:
+    "*": ask
+    "git status*": allow
+    "git diff*": allow
+    "git log*": allow
+    "git show*": allow
+    "git rev-parse*": allow
+    "git commit*": deny
+    "git push*": deny
+  external_directory: deny
+---
+
+Use the `review-change` skill. Review the exact supplied base-to-head diff,
+acceptance criteria, relevant design/API, repository context, and validation
+evidence without relying on the implementing agent's private reasoning.
+
+Confirm the exact base and head snapshots before reviewing. If the diff,
+authority, acceptance criteria, or builder evidence is missing or ambiguous,
+return `BLOCKED BY MISSING EVIDENCE` rather than reconstructing it from chat.
+
+Prioritize correctness, security/privacy, data loss, concurrency, compatibility,
+error behavior, test quality, architecture, scope, maintainability, and rollout.
+Lead with actionable findings ordered P0 through P3. Give a tight location,
+evidence, impact, and testable correction for each finding.
+
+Do not edit code or planning artifacts. Do not invent requirements, block on
+personal style, communicate with the builder directly, or authorize merge. End
+with `READY FOR HUMAN APPROVAL`, `CHANGES REQUIRED`, or
+`BLOCKED BY MISSING EVIDENCE` and name residual risks.

codev_workflow/bundle/AGENTS.md

@@ -0,0 +1,23 @@
+# Human-AI Development Policy
+
+Read `docs/for-ai/WORKFLOW-AGENTS.md` before planning or implementing product
+work. Use the applicable repository skill:
+
+- `specify-project` for a recommendation-led greenfield or whole-product
+  interview that produces one accepted `SPECIFICATION.md`;
+- `define-product` for ideas, outcomes, scope, and workflow sizing;
+- `design-solution` for material architecture, API, data, or risk decisions;
+- `plan-delivery` for multi-developer milestones and work coordination;
+- `build-change` for interactive implementation of one bounded change;
+- `review-change` for an independent, read-only code review; and
+- `launch-product` for readiness, rollout, rollback, and learning.
+
+Use the lightest safe path. Inspect the repository before prescribing code
+mechanics, keep changes small, run proportionate validation, and stop for
+material decisions instead of inventing them. Humans retain authority for
+acceptance, merge, deployment, migration, publication, and rollout expansion.
+
+Do not require developers to choose a skill. Route their request internally and
+describe the current human-facing step as `Understand`, `Build`, `Review`, or
+`Ship`; insert design or delivery planning only when risk or coordination needs
+it.