Skip to content

Product Management Repositories

Product Management repositories coordinate a product across one or more implementation repositories. They are sometimes called product-main repositories.

They exist so product planning can move quickly without changing the shared Engineering Platform every time a roadmap, feature, release, or product decision changes.

Purpose

A product-main repository owns product and program management for one product.

It should contain:

  • Product vision and product goals.
  • Product architecture at the component level.
  • Product roadmap and release planning.
  • Product capability map.
  • Product repository registry.
  • Cross-repository feature plans.
  • Repository impact analyses.
  • GitHub issue and GitHub Project task creation.
  • Product progress sync from issues, PRs, and project fields.
  • Product-specific playbooks.
  • Product ADRs.
  • Product prompts and templates.
  • Product MkDocs source docs, published through anuva-dev-docs when configured.

It should not contain implementation code.

Position in the Organization

flowchart TD
  org["Shoonya Organization"] --> platform["Engineering Platform"]
  org --> product["Product"]

  platform --> handbook["anuva-engineering-handbook"]
  product --> main["product-main repository"]
  main --> project["GitHub Project"]
  main --> repoA["implementation repository A"]
  main --> repoB["implementation repository B"]
  main --> repoC["implementation repository C"]
  project --> repoA
  project --> repoB
  project --> repoC

  handbook -. "shared process, templates, prompts" .-> main
  handbook -. "shared engineering standards" .-> repoA
  handbook -. "shared engineering standards" .-> repoB
  handbook -. "shared engineering standards" .-> repoC

The Engineering Platform defines how work should be done. The product-main repository defines what the product needs. Implementation repositories define how their component is built.

Current and Future Examples

Product Product Management Repository Implementation Repositories
Video Creator anuva-main-video-creator anuvax-cms, anuva-python-server, anuva-unity-video-creator
Realtime anuva-main-realtime Future Realtime implementation repositories such as anuva-unity-realtime

These examples describe hierarchy only. Product-specific implementation guidance belongs in the product-main repository or the owning implementation repository.

Standard Product-Main Flow

flowchart TD
  idea["Product idea or roadmap item"] --> productBrief["Product-level brief"]
  productBrief --> capabilityImpact["Capability impact"]
  capabilityImpact --> repoImpact["Repository impact analysis"]
  repoImpact --> taskSpec["tasks.yml and handoff prompts"]
  taskSpec --> github["GitHub issues and project items"]
  github --> implementation["Implementation repositories"]
  implementation --> verification["Repository verification and PR completion reports"]
  verification --> githubSync["Issue and GitHub Project status sync"]
  githubSync --> productReview["Product release review"]
  productReview --> releaseNotes["Product release notes"]

GitHub Project Coordination

For Video Creator, anuva-main-video-creator coordinates the Anuva Video Creator GitHub Project.

The product-main repository should:

  • create feature docs before implementation begins
  • identify affected repositories and ownership boundaries
  • create GitHub issues in implementation repositories
  • add those issues to the Anuva Video Creator GitHub Project
  • track issue, PR, verification, docs, and product review state
  • update product progress docs from GitHub state
  • trigger or document anuva-dev-docs publishing refreshes when docs change

It should not implement Web, Python, or Unity code unless the user explicitly opens the relevant implementation repository and asks Codex to work there.

Example product-main change folder:

docs/changes/2026-07-05-example-feature/
  BrainDump.md
  FeatureBrief.md
  RepositoryImpact.md
  HandoffPrompts.md
  GitHubTasks.md
  Progress.md
  ReviewChecklist.md
  tasks.yml

Example GitHubTasks.md row:

| Repository | Issue | Project status | PR | Verification | Docs impact | Product review |
| --- | --- | --- | --- | --- | --- | --- |
| `anuva-unity-video-creator` | `#52` | Done | `#57` | Passed | Local | Accepted |

Relationship to the Handbook

Product-main repositories should reference this handbook for:

  • AGENTS.md design.
  • Product Main Repository and Implementation Repository change workflow patterns.
  • Docs parity rules.
  • Skill structure.
  • Repository bootstrap expectations.
  • Shared templates and prompts.
  • Capability and repository ownership rules.

They should not copy large sections of handbook content. If a shared process changes, the handbook should change once and products should continue referencing it.

Relationship to Implementation Repositories

Product-main repositories may create plans, handoff prompts, GitHub issues, and GitHub Project items for implementation repositories. Implementation repositories own the actual code changes, tests, local docs, PRs, and verification.

sequenceDiagram
  participant PM as Product Main
  participant GH as GitHub Issues + Project
  participant Web as Web Repository
  participant Server as Server Repository
  participant Runtime as Runtime Repository

  PM->>PM: Plan product feature
  PM->>PM: Record capability and repository impact
  PM->>GH: Create Web, server, and runtime issues
  GH->>Web: Route Web issue
  GH->>Server: Route server issue
  GH->>Runtime: Route runtime issue
  Web-->>GH: Report PR, verification, docs status
  Server-->>GH: Report PR, verification, docs status
  Runtime-->>GH: Report PR, verification, docs status
  GH-->>PM: Sync implementation status
  PM->>PM: Close product-level release checklist

When to Create a Product-Main Repository

Create a product-main repository when a product needs durable coordination across multiple repositories or long-lived product planning.

Good triggers include:

  • More than one implementation repository contributes to the product.
  • Product-level roadmap and release decisions need a durable home.
  • Cross-repository feature planning is frequent.
  • GitHub Project coordination is needed across implementation repositories.
  • Product-specific skills or playbooks are emerging.
  • Product documentation should be published through anuva-dev-docs as part of the aggregated development docs site.

Avoid creating a product-main repository for a small implementation-only experiment that does not yet need product-level coordination.