Skip to content

Product Change Workflow

The Product Change Workflow turns a product request into coordinated repository work while preserving the boundary between product planning and implementation. It follows the product-main pattern defined by anuva-engineering-handbook.

flowchart TD
    Request["Product request or discovery"] --> Scope{"Scope?"}
    Scope --> Small["Small product-doc change"]
    Scope --> Large["Feature or cross-repository change"]
    Small --> Inline["Inline product-doc plan"]
    Inline --> ProductDocs["Update product docs"]

    Large --> BrainDump["BrainDump.md"]
    BrainDump --> Brief["FeatureBrief.md or ChangeBreakdown.md"]
    Brief --> Impact["RepositoryImpact.md"]
    Impact --> Tasks["HandoffPrompts.md, GitHubTasks.md, tasks.yml"]
    Tasks --> Issues["Implementation repository issues"]
    Issues --> Project["Anuva Video Creator GitHub Project"]
    Project --> RepoWork["Implementation repository work"]
    RepoWork --> Reports["PR completion reports and issue updates"]
    Reports --> Progress["Progress.md"]
    Progress --> Review["ReviewChecklist.md"]
    Review --> Release["Release notes and change history"]

Responsibilities

This repository owns:

  • product goals, constraints, non-goals, and acceptance criteria
  • product architecture, product capability map, and product repository registry
  • repository impact analysis and task sequencing
  • GitHub issue and Anuva Video Creator GitHub Project task coordination
  • product progress, integration review, release readiness, and product docs

This repository does not own Web, Python, or Unity implementation code. Implementation work belongs in the implementation repositories listed in the Product Repository Registry.

Change Sizes

Small product-main changes can be planned inline when they only update product docs, prompts, templates, playbooks, release notes, or project metadata.

Use the large workflow when work affects:

  • product behavior or user-facing acceptance criteria
  • more than one implementation repository
  • shared contracts, repository ownership, or capability ownership
  • GitHub Project automation or task routing
  • product release readiness
  • unclear requirements that need product decisions before implementation

Large Product Change Folder

Large product changes should normally use:

docs/changes/<YYYY-MM-DD-feature-name>/
  BrainDump.md
  FeatureBrief.md
  RepositoryImpact.md
  HandoffPrompts.md
  GitHubTasks.md
  Progress.md
  ReviewChecklist.md
  tasks.yml

Use ChangeBreakdown.md instead of FeatureBrief.md when a change begins as exploratory notes rather than a product-ready feature brief.

GitHub Task Handoff

Each non-trivial implementation task should become a GitHub issue and Anuva Video Creator GitHub Project item after the product docs are reviewed.

Issue bodies should include:

  • Product Feature ID
  • Product Change Folder
  • target repository
  • repository-owned scope
  • repository non-goals
  • acceptance criteria
  • docs impact
  • verification expectations
  • product-main sync requirements

Codex chat is not a durable handoff packet. GitHub issues, project fields, PR completion reports, and product-main progress docs are the durable record.

Product-Main Progress

Progress.md and GitHubTasks.md should be updated when:

  • issues are created or scoped
  • implementation starts
  • PRs are opened, merged, or blocked
  • verification passes, fails, or is skipped
  • implementation docs are updated
  • product-level gaps or integration risks are discovered

Docs Parity

Update product-main docs when product behavior, repository ownership, capability ownership, release status, product prompts, templates, or project coordination changes.

Update anuva-engineering-handbook when the change affects shared Anuva process, repository architecture, templates, prompts, skills guidance, publishing structure, or registry source-of-truth rules.

Implementation repository docs should remain in the implementation repositories.

Completion Criteria

A product-main change is complete when:

  • product-level acceptance criteria are satisfied or explicitly deferred
  • implementation repository issues and PRs are linked
  • GitHub Project fields reflect current status
  • verification results are recorded
  • product-main progress and review docs are updated
  • implementation docs are linked or summarized where useful
  • release notes, change history, and publishing refresh notes are updated
  • handbook updates are completed when shared process or registry guidance changed
  • remaining risks and follow-ups are recorded