Skip to content

Cross-Repository Feature Workflow

Cross-repository features need ownership, sequencing, acceptance criteria, task routing, and completion tracking across multiple repositories.

Engineering-wide cross-repository features start in the handbook. Product-specific cross-repository features start in the relevant Product Management repository, such as anuva-main-video-creator for Video Creator.

The coordinating repository creates the plan. GitHub Issues and GitHub Projects carry repository-specific tasks. Implementation still happens inside the owning repositories.

sequenceDiagram
  participant User
  participant Handbook as Handbook
  participant Registry as Registries
  participant ProductMain as Product Main
  participant GitHub as GitHub Issues + Project
  participant RepoA as Repository A
  participant RepoB as Repository B
  participant DevDocs as anuva-dev-docs

  User->>ProductMain: Describe product feature
  ProductMain->>Registry: Check ownership if unclear
  ProductMain->>ProductMain: Create feature brief and repository impact
  ProductMain->>GitHub: Create issues and project items
  GitHub->>RepoA: Route local task
  GitHub->>RepoB: Route local task
  RepoA->>RepoA: Plan, implement, verify, update docs
  RepoB->>RepoB: Plan, implement, verify, update docs
  RepoA->>GitHub: Update issue, PR, project status
  RepoB->>GitHub: Update issue, PR, project status
  GitHub->>ProductMain: Sync implementation progress
  ProductMain->>ProductMain: Integration review
  ProductMain->>DevDocs: Publish updated docs when applicable

When To Use This Workflow

Use this workflow when a feature:

  • affects more than one repository
  • changes shared contracts or capability ownership
  • requires coordinated sequencing
  • has unclear repository ownership
  • creates a new repository or service boundary
  • needs integration-level acceptance criteria
  • changes handbook registries, templates, skills, or standards

For Video Creator, use the GitHub Project Automation workflow whenever the feature produces implementation work in anuvax-cms, anuva-python-server, or anuva-unity-video-creator.

Handbook-Level Artifacts

Create a folder such as:

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

For product-specific Video Creator work, this folder belongs in anuva-main-video-creator. For engineering-wide changes to process, registry, or standards, this folder belongs in anuva-engineering-handbook.

RepositoryImpact.md Structure

RepositoryImpact.md should identify:

  • affected capabilities
  • affected repositories
  • repository-specific tasks
  • sequencing dependencies
  • docs impact
  • verification expectations
  • open questions
  • acceptance criteria

GitHubTasks.md Structure

GitHubTasks.md should identify:

  • feature id
  • product change folder
  • affected repositories
  • GitHub issue links
  • GitHub Project item status
  • linked PRs
  • verification status
  • docs impact
  • product review status

Example:

| Repository | Issue | Project status | PR | Verification | Docs impact | Product review |
| --- | --- | --- | --- | --- | --- | --- |
| `anuvax-cms` | `#123` | In Review | `#130` | Passed | Local | Pending |
| `anuva-python-server` | `#88` | In Progress | - | Pending | Local | Pending |
| `anuva-unity-video-creator` | `#52` | Done | `#57` | Passed | Local | Accepted |

tasks.yml Structure

tasks.yml should provide a machine-readable version of the repository impact when automation will create GitHub issues.

feature_id: 2026-07-05-example-feature
product_repository: anuva-main-video-creator
project: Anuva Video Creator
change_folder: docs/changes/2026-07-05-example-feature
tasks:
  - repository: anuvax-cms
    title: Implement Web portion of the feature
    priority: high
    docs_impact: local
    acceptance_criteria:
      - Web behavior is implemented
      - Web-local docs are updated
      - Web verification is run or skipped with a reason
  - repository: anuva-python-server
    title: Implement server portion of the feature
    priority: high
    docs_impact: local
    acceptance_criteria:
      - Server behavior is implemented
      - API or orchestration docs are updated
      - Server verification is run or skipped with a reason

Feature Lifecycle

stateDiagram-v2
  [*] --> Proposed
  Proposed --> Scoped: feature brief created
  Scoped --> ReadyForTasks: repository impact approved
  ReadyForTasks --> Assigned: GitHub issues and project items created
  Assigned --> InProgress: repository work begins
  InProgress --> IntegrationReview: PRs, issues, and project status complete
  IntegrationReview --> Published: docs, project status, and registries updated
  IntegrationReview --> InProgress: gaps found
  Published --> [*]

Integration Review

The handbook integration review asks:

  • Did every affected repository complete its local work?
  • Do GitHub issues and project items match the actual implementation state?
  • Do linked PRs contain completion reports?
  • Did local verification run?
  • Did local docs update?
  • Did shared capability ownership change?
  • Did shared workflow, skill, standard, template, or prompt guidance change?
  • Are release notes or anuva-dev-docs publishing updates needed?

Completion Criteria

A cross-repository feature is complete when:

  • all repository tasks are complete or explicitly deferred
  • GitHub issues, PRs, and project fields reflect the final state
  • integration acceptance criteria are satisfied
  • handbook registries are updated
  • docs parity is satisfied locally and at handbook level
  • anuva-dev-docs has been refreshed when published docs changed
  • remaining risks are documented