Skip to content

Product Main Repository Change Workflow

This workflow defines how a product-main repository plans, coordinates, tracks, and closes product-level changes across implementation repositories.

Product-main repositories, such as anuva-main-video-creator, own product coordination. They do not own implementation code.

flowchart TD
  idea["Product request or discovery"] --> classify{"Scope?"}
  classify --> small["Small product-doc change"]
  classify --> large["Feature or cross-repository change"]

  small --> inlinePlan["Inline product-doc plan"]
  inlinePlan --> docs["Update product-main docs"]

  large --> brainDump["BrainDump.md"]
  brainDump --> brief["FeatureBrief.md or ChangeBreakdown.md"]
  brief --> impact["RepositoryImpact.md"]
  impact --> tasks["HandoffPrompts.md, GitHubTasks.md, and tasks.yml"]
  tasks --> issues["Implementation repository issues"]
  issues --> project["Product GitHub Project"]
  project --> implementation["Implementation repositories"]
  implementation --> reports["PR completion reports and issue updates"]
  reports --> progress["Product-main Progress.md"]
  progress --> release["ReviewChecklist.md and release notes"]

Product-Main Responsibilities

A product-main repository should:

  • define the product-level goal, constraints, and acceptance criteria
  • identify affected implementation repositories
  • create repository-specific implementation tasks
  • track GitHub issues, pull requests, verification, docs impact, and project status
  • keep product docs, product repository registry, and product capability map in parity
  • summarize implementation results without duplicating implementation repository docs

Implementation details belong in the owning implementation repository.

Change Sizes

Small product-main changes are narrow documentation or coordination updates. They can usually be planned inline.

Use the large workflow when work affects:

  • product behavior or user-facing acceptance criteria
  • more than one implementation repository
  • repository ownership, capability ownership, or shared contracts
  • 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 the change starts as exploratory notes rather than a product-ready feature brief.

Repository Impact

RepositoryImpact.md is the handoff boundary between product-main planning and implementation repository work.

It should identify:

  • affected repositories
  • capability ownership
  • repository-specific scope
  • docs expected in each implementation repository
  • verification expected in each implementation repository
  • cross-repository risks and sequencing

GitHub Task Handoff

Each implementation repository task should become a GitHub issue and GitHub Project item when the work is more than a trivial follow-up.

Issue bodies should include:

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

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

Product-Main Progress

Progress.md should track implementation state across repositories.

flowchart LR
  issue["GitHub issue"] --> pr["Implementation PR"]
  pr --> verification["Verification result"]
  verification --> docs["Docs impact"]
  docs --> project["GitHub Project fields"]
  project --> progress["Product-main Progress.md"]

Progress should be updated when:

  • issues are created or scoped
  • implementation starts
  • PRs are opened or merged
  • 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
  • handbook updates are completed when shared process or registry guidance changed
  • remaining risks and follow-ups are recorded