Repository Impact: Repository-scoped change workflow

Summary

ANU-19 changes the shared Anuva development process and its allowlisted CLI. Product Main owns the command contracts, issue-kind normalization, canonical skills, policy, tests, and cross-repository acceptance. Each implementation repository owns adoption of the new skill, repository instructions, and local workflow documentation.

No product runtime behavior or cross-repository application contract changes. No product ADR is required; the durable engineering-process contract belongs in the existing Product Main workflow and CLI documentation.

Ownership matrix

Repository	Owned scope	Explicit non-goals	Inputs/dependencies	Outputs/contracts	Verification
anuva-main-video-creator	Standalone issue schema/marker; guarded intake; issue normalization; companion Product Main docs delivery; idempotent completion; canonical skills/metadata; removal of both issue-free maintenance skills and the maintenance CLI/tests; AGENTS and engineering docs	Product implementation; arbitrary Linear creation; general multi-repo orchestration	Approved ANU-19 plan; existing child and Product Main phase workflows	CLI foundation and the sole canonical repository-local change workflow	bun run typecheck; bun test; focused integration/recovery tests; CLI help/removal checks; skill validation; recursive index validation; strict docs build
anuva-bento	Adopt repository-change skill and metadata; align AGENTS and local process/bootstrap docs; preserve Bento-specific verification and upstream rules	Product Main CLI implementation; Bento product behavior; upstream sync	Merged Product Main foundation and canonical skill contract	Bento-local implicit repository-change workflow with correct escalation and verification	Skill validation; git diff --check; recursive docs-index validation; strict MkDocs build; no product build for process-only edits
anuvax-cms	Adopt repository-change skill and metadata; align AGENTS and local workflow/bootstrap docs; preserve CMS plan gate and verification routing	CMS runtime/schema/auth/billing changes; Product Main CLI implementation	Merged Product Main foundation and canonical skill contract	CMS-local implicit repository-change workflow with CMS-specific checks and escalation	Skill validation; git diff --check; recursive docs-index validation; strict MkDocs build; lint/typecheck only if non-doc executable files require them
anuva-python-server	Adopt repository-change skill and metadata; align AGENTS and local workflow/bootstrap docs; preserve Python verification and security guidance	Worker behavior or protocol changes; Product Main CLI implementation	Merged Product Main foundation and canonical skill contract	Python-local implicit repository-change workflow with Python-specific checks and escalation	Skill validation; git diff --check; recursive docs-index validation; strict MkDocs build; focused pytest only if executable repository code changes
anuva-unity-video-creator	Adopt repository-change skill and metadata; align AGENTS and local workflow/bootstrap docs; preserve Unity ownership and verification routing	Unity runtime/assets/packages changes; Product Main CLI implementation	Merged Product Main foundation and canonical skill contract	Unity-local implicit repository-change workflow with Unity-specific checks and escalation	Skill validation; git diff --check; recursive docs-index validation; strict MkDocs build; no Unity import/test run for process-only edits

Workflow and CLI contracts

Read-only eligibility preflight

The canonical skill performs open-ended repository and Product Main judgment before invoking any state-changing CLI operation. It inspects repository instructions, likely affected files, active contracts, ownership boundaries, and relevant Product Main pages, then returns exactly one disposition:

• Not required, with evidence that Product Main remains accurate;
• Required, with the bounded Product Main pages expected to need synchronization; or
• Escalate, with the reasons and exact proposed normal Product Main intake.

Escalate creates no standalone Linear issue, branch, change folder, ImplementationPlan, or PR. The CLI owns validation and deterministic mutations, not this open-ended classification.

Intake normalization

Add a typed standalone repository-change intake schema. The implementation plan may refine file and option names, but the user-level operation must:

1. resolve the current configured repository;
2. validate complete scope, acceptance, docs, verification, priority, and a Not required or Required preflight disposition with evidence;
3. dry-run the exact Linear issue, repository label, marker, and branch effects;
4. on confirmation, find or create the marked In Progress issue;
5. create or restore codex/<issue-id>-<slug> from the configured base; and
6. return a receipt that supports identical retry after partial success.

The operation is intentionally repository-change-specific. It must not expose a generic Linear issue-create command. It must reject Escalate, because that disposition never has a standalone repository-change intake.

Issue-kind normalization

Extend issue normalization with an explicit kind:

product-change | implementation-child | standalone-repository-change

Validation rules remain kind-specific:

• a product change is top-level, Product Main-labeled, and managed by change phases;
• an implementation child has a parent, starts Ready, and requires Product Main source/preview inputs;
• a standalone repository change is top-level, marked, repository-labeled, created In Progress, and contains complete local intake inputs.

Product Main-labeled standalone issues must not pass product-change phase commands, and unmarked Product Main parents must not pass repository-change completion.

Implementation PR

Generalize the repository PR create/inspect/ready path to accept a normalized implementation child or standalone repository issue. Preserve:

• branch/issue association;
• configured repository and base validation;
• draft PR creation;
• Linear PR link verification; and
• In Progress-to-In Review transition.

Do not weaken child validation or Product Main source-link requirements.

Product Main docs companion

Add allowlisted operations that:

• start a Product Main companion docs branch derived from the standalone issue;
• require a recorded Required docs disposition and approved implementation plan;
• create and link at most one draft Product Main docs PR;
• leave the standalone issue In Review;
• validate Product Main repository/base/head identity and strict preview evidence; and
• refuse application code, CLI code, product decisions, shared contracts, or process redesign through this companion path.

The implementation plan must choose a deterministic branch suffix and managed Linear link name. The branch and PR must remain distinguishable from Product Main planning/decision/completion phases.

Completion reconciliation

Add one guarded standalone repository-change completion operation. It must:

1. validate the absolute CompletionReport and clean affected worktrees;
2. inspect the implementation PR and optional required docs PR;
3. require both PRs to be ready, mergeable, review-compatible, and green;
4. merge the implementation PR before the Product Main docs PR;
5. verify each merge commit;
6. fast-forward each configured local base;
7. delete and verify local and remote managed branches;
8. write managed delivery/evidence links; and
9. move Linear from In Review to Done only after all required effects verify.

Reuse the existing PR inspection, reviewability, guarded-head merge, cleanup, Linear transition, lock, and receipt primitives. Do not build a generic multi-step workflow runner.

Sequencing and blockers

flowchart LR
    Plan["ANU-19 planning PR merged"]
    Main["Product Main CLI and canonical workflow"]
    Bento["Bento adoption"]
    CMS["CMS adoption"]
    Python["Python adoption"]
    Unity["Unity adoption"]
    Review["Product Main completion review"]

    Plan --> Main
    Main --> Bento
    Main --> CMS
    Main --> Python
    Main --> Unity
    Bento --> Review
    CMS --> Review
    Python --> Review
    Unity --> Review

• The Product Main implementation child has no child dependency.
• All four implementation-repository adoption children depend on the Product Main foundation and remain blocked until it is Done.
• The implementation repositories may proceed in parallel after that dependency clears.
• A decision phase is required if implementation proposes generic Linear issue creation, more than one implementation repository per standalone issue, unattended merge/completion, or a Product Main companion that can change code or decisions.

Repository Linear issue drafts

Product Main: Implement repository-change CLI and canonical workflow

• Client key: product-main-repository-change-foundation
• Repository: anuva-main-video-creator
• Priority: Normal
• Dependencies: None inside ANU-19

Scope

Implement the preflight contract and exact Product Main intake response, typed standalone intake, versioned marker, issue-kind normalization, guarded branch creation, repository PR compatibility, optional Product Main docs companion operations, and idempotent multi-PR completion. Create the canonical anuva-repository-change skill and metadata; generalize the implementation/review skills without weakening child validation; delete both issue-free maintenance skills and the complete maintenance CLI; and align Product Main policy, prompts, templates, and engineering documentation.

Acceptance

• The read-only preflight runs before any standalone mutation or artifact, and Escalate returns an exact Product Main intake without creating them.
• Only Not required and Required intake creates/reuses exactly one marked In Progress issue with the current repository label and managed branch.
• Product parents, children, and standalone issues cannot cross workflow boundaries.
• Plan and completion approval boundaries remain explicit.
• Existing child PR delivery remains compatible.
• Optional Product Main docs delivery is bounded, linked, ordered after implementation, and required before Done.
• Intake and completion retries reconcile every supported partial-failure point.
• Both issue-free maintenance skills, the anuva maintenance namespace, implementation, tests, help, and active documentation are absent with no compatibility or recovery alias.

Docs

Create the Product Main issue implementation folder and plan/log/report. Update AGENTS, Skills, LinearWorkflow, ProductChangeWorkflow, ReviewAndCompletionWorkflow, PromptSkillCliModel, AnuvaCli, CLI implementation plan, repository/process guidance, prompts/templates, navigation, and indexes. Return exact Product Main preview URLs.

Verification

Run bun run typecheck, bun test, focused schema/adapter/command/integration tests for intake, issue kinds, PR links, companion docs, ordering, cleanup, and partial retries, skill validation, git diff --check, recursive docs-index validation, and strict MkDocs preview verification.

Bento: Adopt repository-change workflow

• Client key: bento-repository-change-adoption
• Repository: anuva-bento
• Priority: Normal
• Depends on: product-main-repository-change-foundation

Scope

Delete the Direct Maintenance skill and explicit-only policy, and install the canonical implicit repository-change entry point and its pre-mutation eligibility preflight. Align Bento AGENTS and local process/bootstrap documentation, and adapt shared implementation/review skill copies while preserving upstream, provenance, license, artifact, and Bento-specific verification rules.

Acceptance

• Natural repository-local Bento changes route to the new skill, and escalation produces no standalone issue, branch, artifact, or PR.
• Every mutation and plan remains approval-gated.
• Product/shared-contract, upstream-release, or multi-repository changes escalate correctly.
• Direct Maintenance files and active references are absent.
• Skill copies match the canonical lifecycle with only documented Bento-specific verification differences.

Docs

Create the Bento issue implementation folder and plan/log/report. Update AGENTS, docs/process/ChangeWorkflow.md, bootstrap CLI guidance, navigation/indexes, and other active issue-free maintenance references. Return exact Bento preview URLs.

Verification

Run skill validation, stale-reference search, git diff --check, recursive docs-index validation, and strict MkDocs build/preview. Do not run the product build for process-only edits unless executable Bento files change.

CMS: Adopt repository-change workflow

• Client key: cms-repository-change-adoption
• Repository: anuvax-cms
• Priority: Normal
• Depends on: product-main-repository-change-foundation

Scope

Delete the Direct Maintenance skill and explicit-only policy, and install the canonical implicit repository-change entry point and its pre-mutation eligibility preflight. Align CMS AGENTS and local process/bootstrap documentation, and adapt shared implementation/review skill copies while preserving CMS large-change escalation, plan approval, auth, billing, schema, migration, Playwright, and verification rules.

Acceptance

• Natural repository-local CMS changes route to the new skill, and escalation produces no standalone issue, branch, artifact, or PR.
• Every mutation and plan remains approval-gated.
• Auth, billing, schema/migration, product, shared-contract, and multi-repository changes escalate correctly.
• Direct Maintenance files and active references are absent.
• Skill copies match the canonical lifecycle with only documented CMS-specific verification differences.

Docs

Create the CMS issue implementation folder and plan/log/report. Update AGENTS, docs/process/ChangeWorkflow.md, bootstrap CLI guidance, navigation/indexes, and other active issue-free maintenance references. Return exact CMS preview URLs.

Verification

Run skill validation, stale-reference search, git diff --check, recursive docs-index validation, and strict MkDocs build/preview. Run CMS lint/typecheck or targeted tests only if non-document executable files change.

Python: Adopt repository-change workflow

• Client key: python-repository-change-adoption
• Repository: anuva-python-server
• Priority: Normal
• Depends on: product-main-repository-change-foundation

Scope

Delete the Direct Maintenance skill and explicit-only policy, and install the canonical implicit repository-change entry point and its pre-mutation eligibility preflight. Align Python AGENTS and local process/bootstrap documentation, and adapt shared implementation/review skill copies while preserving service, protocol, security, simulator, operational, and Python-specific verification rules.

Acceptance

• Natural repository-local Python changes route to the new skill, and escalation produces no standalone issue, branch, artifact, or PR.
• Every mutation and plan remains approval-gated.
• Protocol, product, security/privacy, deployment, and multi-repository changes escalate correctly.
• Direct Maintenance files and active references are absent.
• Skill copies match the canonical lifecycle with only documented Python-specific verification differences.

Docs

Create the Python issue implementation folder and plan/log/report. Update AGENTS, docs/process/ChangeWorkflow.md, bootstrap CLI guidance, navigation/indexes, and other active issue-free maintenance references. Return exact Python preview URLs.

Verification

Run skill validation, stale-reference search, git diff --check, recursive docs-index validation, and strict MkDocs build/preview. Run focused pytest only if executable Python files change.

Unity: Adopt repository-change workflow

• Client key: unity-repository-change-adoption
• Repository: anuva-unity-video-creator
• Priority: Normal
• Depends on: product-main-repository-change-foundation

Scope

Delete the Direct Maintenance skill and explicit-only policy, and install the canonical implicit repository-change entry point and its pre-mutation eligibility preflight. Align Unity AGENTS and local process/bootstrap documentation, and adapt shared implementation/review skill copies while preserving Unity ownership, vendor boundaries, serialization, import, render, and verification rules.

Acceptance

• Natural repository-local Unity changes route to the new skill, and escalation produces no standalone issue, branch, artifact, or PR.
• Every mutation and plan remains approval-gated.
• Product/shared-contract, package, protocol, deployment, and multi-repository changes escalate correctly.
• Direct Maintenance files and active references are absent.
• Skill copies match the canonical lifecycle with only documented Unity-specific verification differences.

Docs

Create the Unity issue implementation folder and plan/log/report. Update AGENTS, docs/process/ChangeWorkflow.md, bootstrap CLI guidance, navigation/indexes, and other active issue-free maintenance references. Return exact Unity preview URLs.

Verification

Run skill validation, stale-reference search, git diff --check, recursive docs-index validation, and strict MkDocs build/preview. Do not run Unity import/compile or Test Runner for process-only edits unless Unity executable or serialized files change.

Cross-repository integration verification

Product Main completion review will:

1. Verify all five children are Done and all linked PRs are merged.
2. Inspect the Product Main CLI tests for issue-kind isolation, intake rejection of Escalate, idempotency, companion docs ordering, partial failure, cleanup, and completion.
3. Confirm each repository exposes anuva-repository-change for implicit selection and contains no Direct Maintenance skill or active reference.
4. Compare shared skill lifecycles and document justified repository-specific verification differences.
5. Confirm every AGENTS and active workflow page preserves the three approval boundaries: intake mutation, generated plan, and final completion mutations.
6. Search all active repositories for stale issue-free maintenance guidance, skill metadata, CLI help, implementation, and tests.
7. Run a non-mutating dry-run/fixture scenario for Product Main and at least one implementation repository.
8. Verify an Escalate fixture returns an exact Product Main issue proposal and leaves Linear, Git, documentation, and GitHub unchanged.
9. Confirm the anuva maintenance command group is absent and no configured repository contains a surviving maintenance branch or open maintenance PR.

Product Main sync and completion

• Keep ANU-19 In Progress throughout planning and child delivery.
• Record created child IDs and dependency relations after the planning PR merges.
• Update this folder as each child plans, delivers, and completes.
• Begin Product Main completion review only when every child is Done or intentionally Canceled.
• Require a completion-phase Product Main PR that records cross-repository acceptance and any release/rollout limitations.
• Move ANU-19 to Done only after that completion PR merges.