Skip to content

GitHub Project Automation

Anuva uses GitHub Issues and GitHub Projects as the automation layer between product planning, repository implementation, progress tracking, and published documentation.

The goal is that humans provide product and implementation decisions while Codex and scripts handle the repeatable routing work:

  • create repository-specific issues from product-main feature docs
  • add those issues to the Anuva Video Creator GitHub Project
  • keep implementation progress visible by repository
  • capture completion through pull requests and issue comments
  • rebuild the public development docs site through anuva-dev-docs

Current Scope

This workflow applies to the current Video Creator repositories.

Repository Role in automation
anuva-main-video-creator Product source of truth for Video Creator features, repository impact, GitHub task creation, product progress, and release review.
anuvax-cms Web implementation repository. Receives GitHub issues as handoff packets and reports completion through PRs, issue updates, and local docs.
anuva-python-server Python server implementation repository. Receives render orchestration tasks and reports completion through PRs, issue updates, and local docs.
anuva-unity-video-creator Unity implementation repository. Receives Unity runtime/editor tasks and reports completion through PRs, issue updates, and local docs.
anuva-engineering-handbook Shared process, registry, template, and prompt source of truth.
anuva-dev-docs Aggregated static documentation publisher for all Anuva development docs.

Core Model

flowchart TD
  chat["User and Codex brainstorm feature"] --> mainDocs["anuva-main-video-creator\nFeature docs"]
  mainDocs --> taskSpec["Repository task specs"]
  taskSpec --> issues["GitHub Issues\nin implementation repos"]
  issues --> project["Anuva Video Creator\nGitHub Project"]

  project --> repoWork["Implementation repo Codex sessions"]
  repoWork --> prs["Pull requests\nwith completion reports"]
  prs --> issueUpdates["Issue comments, labels,\nand status updates"]
  issueUpdates --> project

  project --> mainProgress["anuva-main-video-creator\nProgress and review docs"]
  mainProgress --> devDocs["anuva-dev-docs\naggregate build"]
  repoWork --> localDocs["Local repository docs"]
  localDocs --> devDocs
  devDocs --> cloudflare["Cloudflare Pages\nanuva.girishd.com"]

The durable source of truth is not the Codex chat. The durable handoff is the GitHub issue, backed by product-main docs and tracked in the GitHub Project.

Product-Main Change Folder

For a cross-repository Video Creator feature, anuva-main-video-creator should create a change folder such as:

docs/changes/<YYYY-MM-DD-feature-name>/
  BrainDump.md
  FeatureBrief.md
  RepositoryImpact.md
  HandoffPrompts.md
  GitHubTasks.md
  Progress.md
  ReviewChecklist.md
  tasks.yml
File Purpose
BrainDump.md Raw feature notes, user intent, constraints, and unresolved thinking.
FeatureBrief.md Product-level goals, non-goals, user impact, acceptance criteria, and product behavior.
RepositoryImpact.md Affected repositories, ownership boundaries, sequencing, docs impact, and verification expectations.
HandoffPrompts.md Human-readable prompts that explain what each implementation repository should do.
GitHubTasks.md Created issue links, project item links, PR links, current status, and synchronization notes.
Progress.md Product-level implementation progress grouped by repository.
ReviewChecklist.md Integration review checklist before the feature is considered complete.
tasks.yml Machine-readable task definitions used by scripts or Codex to create GitHub issues.

Example Task Definition

tasks.yml should be concise enough for automation and explicit enough for Codex to create good issues.

feature_id: 2026-07-05-shot-template-library
product_repository: anuva-main-video-creator
project: Anuva Video Creator
change_folder: docs/changes/2026-07-05-shot-template-library
tasks:
  - repository: anuvax-cms
    title: Add Web management UI for shot templates
    type: implementation
    priority: high
    labels:
      - video-creator
      - product-feature
      - docs-impact
    product_context:
      - FeatureBrief.md
      - RepositoryImpact.md
    owns:
      - Web UI for browsing, creating, and editing shot templates
      - Web-local docs for the management flow
    does_not_own:
      - Python rendering behavior
      - Unity runtime template playback
    acceptance_criteria:
      - Users can create and edit shot templates from the Web app
      - UI behavior is documented in local Web docs
      - Relevant Web checks are run or skipped with a reason

  - repository: anuva-python-server
    title: Add server contract for shot template render requests
    type: implementation
    priority: high
    labels:
      - video-creator
      - product-feature
      - api-contract
    owns:
      - Server-side request validation
      - Render orchestration contract
      - Server-local docs for the API and state flow
    acceptance_criteria:
      - Web can submit a shot template render request
      - Unity receives the expected render payload
      - API contract docs are updated

  - repository: anuva-unity-video-creator
    title: Support shot template playback in Unity render scene
    type: implementation
    priority: high
    labels:
      - video-creator
      - product-feature
      - unity
    owns:
      - Unity scene behavior for template playback
      - Unity-local docs for render scene expectations
    acceptance_criteria:
      - Unity can consume the server payload
      - Template playback works in the render scene
      - Unity verification is run or skipped with a reason

GitHub Issue as Handoff Packet

Each implementation issue should contain enough context for Codex to work inside that repository without reading the full product-main history.

Product Feature ID:
2026-07-05-shot-template-library

Product Source:
anuva-main-video-creator/docs/changes/2026-07-05-shot-template-library/

Repository:
anuva-unity-video-creator

Task Summary:
Support shot template playback in the Unity render scene.

Product Context:
- This feature lets Video Creator users define reusable shot templates.
- Web owns management UI.
- Python owns request validation and render orchestration.
- Unity owns playback/render behavior for the final payload.

This Repository Owns:
- Unity scene behavior for template playback.
- Unity-local docs for render scene expectations.

This Repository Does Not Own:
- Web management UI.
- Python API validation.
- Product roadmap decisions.

Acceptance Criteria:
- Unity can consume the server payload.
- Template playback works in the render scene.
- Unity docs under docs/core, docs/state, or docs/process are updated where behavior changed.
- Unity verification is run or skipped with a reason.

Completion Report Required:
- Implementation summary.
- Files changed.
- Docs updated.
- Verification run.
- Integration notes for anuva-main-video-creator.
- Open questions or follow-ups.

GitHub Project Fields

The Anuva Video Creator GitHub Project should be configured so progress can be grouped by repository and feature.

Field Example values Purpose
Status Backlog, Ready, In Progress, In Review, Done, Blocked Kanban state for the task.
Repository anuvax-cms, anuva-python-server, anuva-unity-video-creator, anuva-main-video-creator Groups work by owning repository.
Feature ID 2026-07-05-shot-template-library Links all tasks for one feature.
Product Change Folder docs/changes/2026-07-05-shot-template-library Points back to product-main docs.
Priority High, Medium, Low Helps sequence implementation.
Docs Impact None, Local, Product, Handbook, Publisher Signals documentation work required.
PR Pull request URL or number Connects task tracking to implementation.
Verification Pending, Passed, Skipped, Failed Summarizes local verification state.

Automated Development Flow

sequenceDiagram
  participant User
  participant Main as anuva-main-video-creator
  participant GH as GitHub Issues + Project
  participant Repo as Implementation repository
  participant PR as Pull request
  participant DevDocs as anuva-dev-docs
  participant CF as Cloudflare Pages

  User->>Main: Brainstorm and finalize feature with Codex
  Main->>Main: Create FeatureBrief, RepositoryImpact, tasks.yml
  User->>Main: Review docs and answer open questions
  Main->>GH: Create implementation issues and project items
  User->>Repo: Ask Codex to list and select an issue
  Repo->>Repo: Implement, update local docs, run verification
  Repo->>PR: Open or update PR with completion report
  PR->>GH: Link PR, update issue, update project fields
  GH->>Main: Sync progress into product-main docs
  Main->>DevDocs: Trigger aggregate docs build
  DevDocs->>DevDocs: Build MkDocs output for all repositories
  DevDocs->>CF: Commit/publish static site update

Implementation Repository Completion

Implementation work should close the loop through the issue and pull request. A PR description should include:

Product Feature ID:
Product Change Folder:
GitHub Issue:
Repository:

Implementation Summary:

Docs Updated:

Verification Run:

Verification Skipped:

Integration Notes for anuva-main-video-creator:

Open Questions:

Follow-ups:

Codex should update the GitHub Project item when a PR moves through the workflow:

Event Expected project update
Issue created Status = Backlog or Ready
Codex starts implementation Status = In Progress
PR opened Status = In Review, PR = <url>
Verification passes Verification = Passed
Verification skipped Verification = Skipped with issue comment explaining why
PR merged or task accepted Status = Done
Blocking question found Status = Blocked with issue comment and owner

Progress Sync Back To Product Main

anuva-main-video-creator should record progress from GitHub rather than relying on chat memory.

GitHubTasks.md can use a table like:

| 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 |

Progress.md should summarize human-readable state:

## Repository Progress

### anuvax-cms

Status: In Review

The Web implementation is complete and awaiting product review. Local Web docs were updated for the shot template management flow.

### anuva-python-server

Status: In Progress

The server contract is being implemented. The current open question is whether template validation should reject missing optional camera parameters or fill defaults.

### anuva-unity-video-creator

Status: Done

Unity playback support is complete. Verification passed in the local Unity render scene.

anuva-dev-docs Publishing

anuva-dev-docs is the active aggregated documentation publisher. It should build MkDocs output from each Anuva repository and publish a static site where index.html is the homepage.

Expected output layout:

anuva-dev-docs/
  index.html
  project-status.html
  handbook/
  main-video-creator/
  anuvax-cms/
  anuva-python-server/
  anuva-unity-video-creator/

Each repository should eventually provide:

mkdocs.yml
hooks.py
docs/
  stylesheets.css
  *.md

Some repositories may be onboarded later. The publisher should skip or clearly report repositories that do not yet have MkDocs configured.

Publishing Automation

flowchart TD
  trigger{"Publish trigger"} --> manual["Manual batch file\nin anuva-dev-docs"]
  trigger --> dispatch["GitHub Actions\nworkflow_dispatch"]
  trigger --> repoDispatch["repository_dispatch\nfrom source repo"]
  trigger --> schedule["Scheduled refresh"]

  manual --> build["Build all MkDocs sites"]
  dispatch --> build
  repoDispatch --> build
  schedule --> build

  build --> collect["Copy static HTML into\nrepository subfolders"]
  collect --> projectStatus["Generate project-status.html\nfrom GitHub Project"]
  projectStatus --> commit["Commit generated static output\nor update deploy artifact"]
  commit --> cloudflare["Cloudflare Pages deploy"]

For local use, anuva-dev-docs may provide a root batch file:

@echo off
powershell -ExecutionPolicy Bypass -File scripts\build-all-docs.ps1

The PowerShell script should:

  • locate the sibling repositories
  • run mkdocs build in each repository that has mkdocs.yml
  • copy each generated site into the correct anuva-dev-docs subfolder
  • generate project-status.html from the Anuva Video Creator GitHub Project
  • leave a clear summary of successful, skipped, and failed builds

User Interaction Model

The intended human workflow is:

  1. In anuva-main-video-creator, brainstorm a feature with Codex.
  2. Ask Codex to write product feature docs and repository impact docs.
  3. Review the docs and answer open questions.
  4. Ask Codex to create GitHub issues and add them to the Anuva Video Creator GitHub Project.
  5. In an implementation repository, ask Codex to list available issues for that repository.
  6. Select an issue and work through the implementation repository docs/process/ChangeWorkflow.md.
  7. Test the implementation.
  8. Ask Codex to update the issue, PR, project item, and product-main progress docs.
  9. Let anuva-dev-docs rebuild and publish the aggregated docs site.

Example Prompts

Create GitHub tasks from product-main:

Create GitHub implementation tasks for this feature.

Read the current feature docs:
- FeatureBrief.md
- RepositoryImpact.md
- HandoffPrompts.md
- tasks.yml

For each repository task:
- create or update a GitHub issue in the owning repository
- add the issue to the Anuva Video Creator GitHub Project
- set Repository, Feature ID, Product Change Folder, Priority, Docs Impact, and Status fields
- update GitHubTasks.md with issue and project links

Do not implement repository code.
Summarize created issues, skipped issues, and any GitHub CLI commands that failed.

Select implementation work from a repository:

List open Anuva Video Creator GitHub Project issues for this repository.

Group them by Status and Priority.
Show the issue title, Feature ID, Docs Impact, and Product Change Folder.
After I choose one, use the issue body as the product-main handoff context and follow this repository's docs/process/ChangeWorkflow.md.

Close implementation work:

Update the GitHub issue, PR description, GitHub Project fields, and product-main progress docs for this completed task.

Include:
- implementation summary
- files changed
- docs updated
- verification run or skipped
- integration notes
- open questions
- follow-ups

Set the project status based on the actual task state.
Trigger or document the required anuva-dev-docs publishing refresh.

Completion Criteria

The automated workflow is working when:

  • product-main feature docs can generate implementation issues
  • implementation issues appear in the Anuva Video Creator GitHub Project
  • Codex can list repository-specific issues from an implementation repository
  • PRs include completion reports and link back to product-main feature docs
  • product-main progress docs can be updated from issue and PR state
  • anuva-dev-docs can publish handbook, product-main, and implementation docs to the aggregated site
  • project-status.html shows GitHub Project issues grouped by repository