Skip to content

Codex Development Architecture

Anuva's Codex development architecture separates knowledge, policy, procedure, and implementation. This keeps Codex sessions focused while preserving enough shared context for cross-repository work.

flowchart TD
  handbook["anuva-engineering-handbook"] --> docs["Documentation\nWhat is true"]
  handbook --> registries["Registries\nWho owns what"]
  handbook --> templates["Templates and prompts\nWhere to start"]

  productMain["anuva-main-video-creator"] --> featureDocs["Product feature docs\nWhat the product needs"]
  productMain --> githubTasks["GitHub issues and project items\nWhat should be done"]
  repo["Owning repository"] --> agents["AGENTS.md\nRepository rules"]
  repo --> localDocs["Local docs\nImplementation context"]
  devDocs["anuva-dev-docs"] --> published["Published docs\nWhat is discoverable"]
  futureSkills["anuva-shared-skills\nReusable procedures"] --> skill["Relevant SKILL.md"]

  docs --> codex["Codex session"]
  registries --> codex
  templates --> codex
  featureDocs --> codex
  githubTasks --> codex
  agents --> codex
  localDocs --> codex
  published --> codex
  skill --> codex

  codex --> plan["Plan"]
  plan --> work["Implement or document"]
  work --> verify["Verify"]
  verify --> parity["Update docs, issues, projects,\nand registries"]

Core Separation

Element Primary Question Owned By
Handbook docs What is Anuva's engineering operating model? anuva-engineering-handbook
Repository registry Which repositories exist and what are they for? anuva-engineering-handbook
Capability registry Which repository owns each capability? anuva-engineering-handbook
Product feature docs What should Video Creator do and how does a feature affect repositories? anuva-main-video-creator
GitHub issues and project items What implementation tasks are ready, in progress, blocked, or done? anuva-main-video-creator coordinates; owning repositories execute
AGENTS.md How should Codex behave in this repository? Each repository
Local docs What is true about this repository's implementation? Each repository
Skills How should Codex perform repeatable work? Planned anuva-shared-skills, initially defined by handbook
Standards What rules should apply across repositories? Planned anuva-shared-standards, initially defined by handbook
Aggregated docs publisher How are repository docs built into a public static site? anuva-dev-docs

Codex Session Modes

Codex work should usually happen in one of four modes.

Mode Starting Repository Purpose Expected Output
Handbook planning anuva-engineering-handbook Define architecture, ownership, cross-repository plans, registries, and process. Docs, registry updates, task plans
Product planning Product Management repository Define product roadmap, product architecture, product feature plans, repository impact, and releases. Product docs, task prompts, release plans
Product task automation anuva-main-video-creator Convert reviewed product feature docs into GitHub issues and Anuva Video Creator GitHub Project items. Issues, project items, GitHubTasks.md, progress docs
Repository implementation Owning implementation repository Implement scoped code or docs changes. Code, tests, local docs
Repository onboarding New or existing repository Bring a repository into handbook compliance. AGENTS.md, local workflow docs, registry entries
Publishing anuva-dev-docs Build MkDocs output from Anuva repositories, generate project status HTML, and publish the static docs site. Published site, status page, build summary

Cross-Repository Work

Engineering-wide cross-repository work should start in the handbook. Product-specific cross-repository work should start in the relevant Product Management repository, then become GitHub issues and project items for implementation repositories.

sequenceDiagram
  participant User
  participant Handbook as anuva-engineering-handbook
  participant ProductMain as Product Main
  participant GitHub as GitHub Issues + Project
  participant Repo as Owning repositories
  participant DevDocs as anuva-dev-docs

  User->>Handbook: Change shared process or ownership model
  Handbook->>Handbook: Update shared docs, registries, templates, or prompts
  User->>ProductMain: Plan product feature or release
  ProductMain->>ProductMain: Create product plan and repository impact
  ProductMain->>GitHub: Create implementation issues and project items
  GitHub->>Repo: Provides repository-specific task handoff
  Repo->>Repo: Implement, verify, update local docs
  Repo->>GitHub: Update issue, PR, project fields, completion report
  GitHub->>ProductMain: Sync progress and product impact
  ProductMain->>Handbook: Request registry updates if shared ownership changes
  ProductMain->>DevDocs: Trigger aggregated docs refresh when applicable

Prompt Context Handoff

Codex sessions are repository-scoped. Context from anuva-main-video-creator should be carried into implementation repositories through durable GitHub issues, not through hidden chat memory.

flowchart LR
  main["anuva-main-video-creator"] --> docs["FeatureBrief.md\nRepositoryImpact.md"]
  docs --> issue["GitHub issue\nhandoff packet"]
  issue --> project["GitHub Project item"]
  project --> repo["Implementation repo Codex session"]
  repo --> pr["PR completion report"]
  pr --> project
  project --> progress["Product-main Progress.md"]

The issue should include the feature id, product-main change folder, repository ownership boundary, acceptance criteria, docs impact, and verification expectations.

Repository-Level Codex Contract

Each repository should eventually provide:

  • AGENTS.md for repository-specific Codex behavior.
  • A local change workflow or pointer to the shared workflow.
  • Local docs for implementation context.
  • Verification commands.
  • A clear statement of what the repository owns and does not own.
  • GitHub issue and PR conventions when the repository participates in product-main automation.

The handbook should provide:

  • Shared workflow architecture.
  • Repository and capability registries.
  • Templates for repository onboarding.
  • Prompts for common Codex tasks.
  • Skill architecture and eventually links to reusable skills.

anuva-main-video-creator should provide:

  • Product feature docs.
  • Repository impact docs.
  • Machine-readable task definitions where useful.
  • GitHub issues and Anuva Video Creator GitHub Project items.
  • Progress and release review docs.

anuva-dev-docs should provide:

  • Aggregated static docs output.
  • A homepage linking to each repository docs site.
  • A project status page grouped by repository.
  • Local and CI publishing scripts.

Planned Skill Flow

flowchart LR
  request["Task request"] --> classify{"Recurring workflow?"}
  classify -->|yes| loadSkill["Load relevant skill"]
  classify -->|no| useDocs["Use docs and repository guidance"]
  loadSkill --> execute["Execute with repository context"]
  useDocs --> execute
  execute --> artifact["Code, docs, plan, or verification"]
  artifact --> improve{"Reusable lesson?"}
  improve -->|yes| updateSkill["Update skill or template"]
  improve -->|no| done["Done"]

Current Boundaries

This page defines the operating architecture for Codex. It does not define implementation details for anuvax-cms, anuva-python-server, or anuva-unity-video-creator.

Detailed repository guidance belongs in the owning implementation repository. Product-level feature context belongs in anuva-main-video-creator. Aggregated publishing mechanics belong in anuva-dev-docs.