Skip to content

Implementation Plan: ANU-24 - Adopt Repository-change Workflow in Anuva Unity Video Creator

Scope

  • Replace the explicit-only, issue-free Direct Maintenance entry point with the canonical implicit-or-explicit $anuva-repository-change workflow and its discovery metadata.
  • Require a read-only repository ownership, eligibility, contract, and Product Main documentation preflight before any standalone Linear issue, branch, change artifact, or PR exists.
  • Preserve three independent approval boundaries:
  • the exact standalone intake or implementation-child start mutation;
  • the generated ImplementationPlan; and
  • PR readiness, merge, branch cleanup, base synchronization, evidence recording, and Linear completion.
  • Normalize the checked-in validation, implementation, and review skills for Product Main-created implementation children and marked standalone repository-change issues.
  • Remove Direct Maintenance skill files, discovery metadata, active policy, bootstrap help, and workflow references without a compatibility alias.
  • Align AGENTS.md, local workflow documentation, and CLI bootstrap guidance while retaining Unity ownership, third-party/vendor boundaries, .meta and serialization safety, package and protocol escalation, render/capture verification, and docs-preview rules.
  • After this plan receives separate approval, add the ANU-24 ImplementationLog and CompletionReport and deliver the process-only change through the guarded implementation-child PR lifecycle.

Product Main inputs and dependencies

  • Linear issue: ANU-24, Adopt repository-change workflow in Anuva Unity Video Creator.
  • Parent issue: ANU-19, Introduce repository-scoped change workflow and remove issue-free maintenance.
  • Product Main source: docs/changes/2026-07-28-anu-19-repository-change-workflow/index.md.
  • Product Main review preview: https://main1.girishd.com/changes/2026-07-28-anu-19-repository-change-workflow/.
  • Repository label: anuva-unity-video-creator.
  • Blocker: ANU-20 is Done.
  • Product Main foundation:
  • main commit 90837acdcff768558554c8b029b6dea67b461ce9;
  • canonical $anuva-repository-change, $linear-implement-issue, $anuva-implement-issue, and $anuva-review-and-complete-pr skills; and
  • installed anuva repository-change CLI namespace with guarded intake, Product Main documentation companion, and completion operations.
  • Planning base: Unity main at f111578b164df0a78f51f7d77e73584bbeaa9c4b.
  • Product Main documentation disposition: Not required for this implementation child. ANU-19 already defines the product-wide workflow, issue-kind and CLI contracts, canonical skills, repository ownership matrix, rollout sequencing, and cross-repository acceptance. ANU-24 changes only Unity-owned skill copies, policy, and local process/bootstrap documentation. Product Main progress and completion evidence remain owned by ANU-19 rather than a companion PR from this child.
  • Revalidate that disposition before implementation and again in the CompletionReport. Any new product decision, shared-contract change, package/dependency change, Unity/Python protocol change, multiple implementation repositories, migration, authentication or authorization, privacy, security, billing, deployment architecture, release coordination, or ownership uncertainty stops work and returns to Product Main.

Implementation approach

1. Install the canonical repository-change entry point

  • Delete:
  • .agents/skills/anuva/anuva-direct-maintenance/SKILL.md; and
  • .agents/skills/anuva/anuva-direct-maintenance/agents/openai.yaml.
  • Add the Product Main canonical copies of:
  • .agents/skills/anuva/anuva-repository-change/SKILL.md; and
  • .agents/skills/anuva/anuva-repository-change/agents/openai.yaml.
  • Keep the skill limited to the required instructions and discovery metadata. Do not add a README, compatibility shim, deprecated alias, or local duplicate of the Product Main CLI contract.
  • Preserve the canonical implicit trigger for natural repository-local changes. Implicit selection routes the workflow only; it never authorizes intake, planning, implementation, PR, merge, cleanup, or Linear mutations.

2. Normalize shared lifecycle skills

  • Update $linear-implement-issue from the merged Product Main canonical lifecycle so it:
  • validates either an implementation child or a marked standalone repository-change issue;
  • retains kind-specific parent, marker, state, repository-label, preflight, and Product Main-link validation; and
  • rejects Product Main parents and ambiguous or malformed top-level issues.
  • Update $anuva-implement-issue from the canonical lifecycle so it:
  • starts Ready children only after approval of the exact anuva work start mutation;
  • accepts already-started standalone issues only on their exact managed branch;
  • revalidates repository ownership, affected contracts, and Product Main disposition before artifacts;
  • enforces the subsequent exact-plan approval gate;
  • uses guarded stage, commit, draft implementation PR, and optional bounded Product Main documentation companion operations; and
  • never readies, merges, cleans branches, or completes Linear in the implementation turn.
  • Update $anuva-review-and-complete-pr from the canonical lifecycle so it:
  • reviews either supported issue kind and all applicable PRs;
  • revalidates evidence, checks, previews, and Product Main disposition;
  • pauses for explicit completion approval; and
  • uses implementation-first guarded completion with retryable cleanup and Linear reconciliation.
  • Preserve only documented Unity-specific additions to the canonical skills:
  • run Unity import/compile and applicable EditMode, PlayMode, or manual render/capture checks when executable or serialized Unity assets change;
  • skip Unity import and Test Runner for process-only Markdown and skill metadata edits, recording the exact changed-file evidence;
  • preserve first-party Assets/Anuva/ ownership, vendor/plugin boundaries, .meta pairing, serialized asset safety, package/project state, PresentationConfig cross-repository contract, Unity/Python protocol, scenes, virtual screens, capture, and rendering expectations;
  • validate recursive docs indexes and strict Unity MkDocs previews; and
  • retry GitHub authentication read-only in the managed keyring-capable context before asking the user to reauthenticate.
  • Align agents/openai.yaml descriptions and prompts with the supported issue kinds. Leave $anuva-preview-docs and $linear-list-ready-issues unchanged unless validation exposes a direct incompatibility with the merged foundation.

3. Align Unity policy and workflow documentation

  • Replace Direct Maintenance authorization in AGENTS.md with the implicit repository-change route and its read-only pre-mutation preflight.
  • State that Escalate returns an exact Product Main Backlog intake and creates no standalone issue, branch, artifact, or PR.
  • Make Unity escalation boundaries explicit:
  • product decisions and shared cross-repository contracts;
  • more than one implementation repository;
  • packages or framework upgrades;
  • PresentationConfig or Unity/Python protocol changes;
  • migrations, authentication or authorization, privacy, security, billing, deployment architecture, release coordination, and ownership uncertainty.
  • Preserve the current Unity repository role, first-party and vendor ownership boundaries, .meta requirements, package/project rules, docs routing, Unity executable path, import/test commands, and render/capture evidence policy.
  • Rewrite docs/process/ChangeWorkflow.md to show:
  • the existing Product Main child path;
  • the new repository-local preflight and Not required/Required standalone intake path;
  • the mutation, plan, and completion approval gates;
  • the no-side-effect Escalate exit;
  • optional bounded Product Main documentation delivery; and
  • implementation-first merge, cleanup, and Linear Done sequencing.
  • Update docs/bootstrap/AnuvaCli.md to replace the removed anuva maintenance --help surface with anuva repository-change --help and describe the Product Main-owned guarded namespace without duplicating its implementation contract.
  • Align docs/bootstrap/BootstrapContext.md, docs/bootstrap/index.md, docs/process/index.md, and docs/index.md only where their existing planned-work-only, direct-maintenance, or superseded GitHub-handoff wording would omit or misdescribe the new path.
  • Do not change Unity scripts, assemblies, scenes, prefabs, serialized assets, packages, ProjectSettings, StreamingAssets, vendor assets, Python protocol, render behavior, capture behavior, or tests.

4. Record and deliver the implementation

  • After explicit approval of this exact plan, create:
  • ImplementationLog.md with timestamps, source commit identities, exact edits, commands, validator versions, skipped Unity checks, and no-side-effect evidence; and
  • CompletionReport.md mapping every ANU-24 acceptance item to exact files, diffs, commands, preview URLs, and limitations.
  • Update this change index, docs/changes/index.md, and mkdocs.yml as those records become available.
  • Use guarded anuva work stage and anuva work commit checkpoints.
  • After all acceptance evidence and previews are complete, run anuva pr create ANU-24 --draft --confirm. Do not ready, merge, delete branches, synchronize main, or mark Linear Done in the implementation turn.

Documentation impact

  • This planning step adds only:
  • this change-folder index;
  • this ImplementationPlan; and
  • the recursive change index and MkDocs navigation entries needed to preview them.
  • After explicit plan approval, update:
  • AGENTS.md;
  • docs/process/ChangeWorkflow.md and docs/process/index.md;
  • docs/bootstrap/AnuvaCli.md, docs/bootstrap/BootstrapContext.md, and docs/bootstrap/index.md where needed for accurate routing;
  • docs/index.md where its Product Main handoff wording is stale;
  • this change's index.md, ImplementationLog.md, and CompletionReport.md;
  • docs/changes/index.md; and
  • mkdocs.yml.
  • The Product Main ANU-19 pages remain the canonical product-wide source. No Product Main companion PR is required for this implementation child.
  • Existing immutable Git/GitHub history remains unchanged even when it records the removed workflow.
  • Preview documentation remains non-canonical until reviewed and merged.

Verification and acceptance checks

  • Foundation and scope:
  • re-read ANU-24 and confirm its repository label, implementation-child kind, parent, Product Main links, In Progress state, and satisfied ANU-20 blocker;
  • confirm Product Main main contains the merged ANU-20 canonical skills and the installed anuva repository-change help surface;
  • compare every local shared lifecycle skill and metadata file with the Product Main canonical copy, allowing only the documented Unity-specific verification and managed-auth differences; and
  • confirm the diff contains no Unity executable, scene, prefab, serialized asset, .meta, package, ProjectSettings, StreamingAssets, vendor, protocol, render, capture, or test file.
  • Skill integrity:
  • run the skill-creator validator against every checked-in Anuva skill folder;
  • inspect YAML frontmatter, lowercase hyphenated names, trigger descriptions, imperative workflow steps, and matching agents/openai.yaml;
  • confirm exactly one repository-local entry point exists and no Direct Maintenance folder, metadata, alias, or recovery command remains; and
  • verify anuva repository-change --help exposes the replacement namespace while root CLI help contains no maintenance command group.
  • Escalation and approval boundaries:
  • forward-test a natural Unity request that proposes a PresentationConfig payload and Unity/Python protocol change and confirm $anuva-repository-change returns Escalate with an exact Product Main issue proposal;
  • snapshot Linear identity, current Git branch and HEAD, worktree status, change-folder inventory, and GitHub PR inventory before and after that scenario to prove no standalone issue, branch, artifact, or PR was created;
  • inspect child and standalone paths for separate intake/start, plan, and completion approvals; and
  • verify the Product Main documentation companion is limited to marked standalone issues with Required disposition and bounded Markdown paths.
  • Active-reference and repository checks:
  • search all active repository content outside .git, immutable historical records, and ANU-24's removal record for anuva-direct-maintenance, Direct Maintenance, issue-free maintenance, anuva maintenance, and codex/maintenance-;
  • inspect local and remote branches plus open PRs for surviving maintenance work requiring recovery;
  • run git diff --check; and
  • run git status --short --branch and record the final scoped file set.
  • Documentation:
  • anuva docs validate-indexes --repository current;
  • anuva docs ensure --repository current --confirm after each logical docs update;
  • anuva docs wait --repository current --file <changed-doc-paths> --since 2026-07-28T19:04:19.0575566Z;
  • anuva docs links --repository current --file <changed-doc-paths>;
  • compare every changed live page with the fresh strict MkDocs build; and
  • return exact HTTPS preview URLs for the ANU-24 overview, ImplementationPlan, workflow, CLI/bootstrap guidance, changes index, ImplementationLog, and CompletionReport as applicable.
  • Because the planned delta is limited to Markdown and skill metadata, do not run Unity import/compile, EditMode, or PlayMode tests. Record that intentional skip with the exact changed-file evidence. If any executable or serialized Unity file enters the diff, run the required Unity import/compile smoke check, applicable Test Runner suites, and any focused manual render/capture checks.

Non-goals and rollback

  • No Product Main CLI, Linear schema, marker, issue-kind, PR adapter, documentation-companion, completion, or recovery implementation.
  • No generic Linear issue creation, GitHub issue, GitHub Project, autonomous mutation, unattended merge, or manual Linear status change.
  • No Product Main decision, shared-contract revision, multi-repository delivery, package/framework upgrade, protocol revision, migration, authentication/authorization, privacy, security, billing, deployment architecture, release-coordination, or product behavior change.
  • No Unity runtime, editor tooling, scene, prefab, serialized asset, virtual screen, presenter, playback/directing, package, capture, render, simulator, or test change.
  • No vendor/plugin asset or package-cache modification.
  • No compatibility alias for Direct Maintenance or anuva maintenance.
  • Before merge, rollback is removal of the new repository-change skill and ANU-24 records plus restoration of prior local skill copies and active policy/docs from the branch base. Immutable history is never rewritten.

Approval

Girish separately approved this exact ImplementationPlan on 2026-07-28 at 19:09 UTC. The earlier approval of anuva work start ANU-24 --confirm did not authorize implementation; this subsequent approval did.