Skip to content

Implementation Plan: ANU-22 - Adopt Repository-change Workflow in Anuva CMS

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 ownership, eligibility, 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, and Linear completion.
  • Normalize the checked-in validation, implementation, and review skills for both 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 CMS ownership, large-change escalation, plan approval, authentication, billing, schema/migration, Playwright, and verification rules.
  • Add the ANU-22 ImplementationLog and CompletionReport after plan approval, then deliver the process-only change through the guarded child PR lifecycle.

Product Main inputs and dependencies

  • Linear issue: ANU-22, Adopt repository-change workflow in Anuva CMS.
  • 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: anuvax-cms.
  • 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 start, Product Main documentation companion, and complete operations.
  • Planning base: CMS main at 64b6df7b37a08635656d57a5e286f7816f2764cb.
  • Product Main documentation disposition: Not required for this implementation child. ANU-19 already defines the product-wide process, canonical skill lifecycle, repository ownership matrix, rollout sequencing, and cross-repository acceptance. ANU-22 changes only CMS-owned skill copies, policy, and local workflow/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, multi-implementation-repository requirement, migration, authentication or authorization change, privacy/security concern, billing change, deployment architecture or release-coordination requirement, 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 concise and limited to its required SKILL.md 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. The implicit trigger selects 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;
  • keeps 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 marked standalone issues only on their exact managed branch;
  • revalidates repository ownership 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, 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 CMS-specific additions to the canonical skills:
  • for process-only changes, record the exact changed-file evidence and why application lint, typecheck, integration, and Playwright checks were not run;
  • if executable CMS files change, run pnpm lint, pnpm typecheck, and the focused tests required by the affected boundary;
  • use pnpm test:int for presentation actions, generation flows, or shared orchestration, and consider pnpm test:e2e for route-level workflow changes;
  • after Payload schema or admin registration changes, run the required generated-file commands before typecheck and targeted tests;
  • preserve workspace/auth, billing, schema/migration, provider/model, and application ownership guardrails;
  • validate recursive indexes and strict CMS MkDocs previews for docs; and
  • retry GitHub authentication read-only in the managed keyring-capable context before asking the user to reauthenticate.
  • Align agents/openai.yaml metadata with each updated skill description and default prompt.
  • Leave $anuva-preview-docs and $linear-list-ready-issues behavior unchanged unless validation identifies a direct incompatibility with the merged foundation.

3. Align CMS policy and workflow documentation

  • Replace the 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 CMS escalation boundaries explicit:
  • product decisions and shared cross-repository contracts;
  • more than one implementation repository;
  • migrations and schema/data cutovers;
  • authentication/authorization, privacy, security, and billing;
  • deployment architecture and release coordination; and
  • uncertain repository ownership.
  • Preserve the current repository role, large-change workflow, exact plan gate, workspace boundary, Payload generation, Mastra provider verification, migration safety, Playwright routing, and CMS verification 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.
  • Update docs/process/index.md so its summary and diagram no longer authorize issue-free maintenance.
  • Do not change CMS runtime behavior, routes, Payload collections, migrations, Mastra workflows, billing, auth, dependencies, or application 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/runtime versions, skipped checks, and no-side-effect evidence; and
  • CompletionReport.md mapping every ANU-22 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 the guarded anuva work stage and anuva work commit checkpoints.
  • After all evidence and previews are complete, run anuva pr create ANU-22 --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;
  • docs/process/index.md;
  • docs/bootstrap/AnuvaCli.md;
  • 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 workflow source. No Product Main companion PR is required for this child.
  • Existing merged change records and immutable Git/GitHub history remain unchanged even if they document the removed workflow historically.
  • Preview documentation remains non-canonical until reviewed and merged.

Verification and acceptance checks

  • Foundation and scope:
  • re-read ANU-22 and confirm its repository label, kind, parent, Product Main links, 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 each local shared lifecycle skill and metadata file with the Product Main canonical copy, allowing only the documented CMS-specific verification and managed-auth differences; and
  • confirm the diff contains no executable CMS, route, collection, migration, auth, billing, Mastra, dependency, or test file.
  • Skill integrity:
  • run the skill-creator quick_validate.py 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 there is no Direct Maintenance folder, metadata, alias, or recovery command; 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 CMS request that requires an auth/schema-migration or shared-contract decision and confirm $anuva-repository-change returns Escalate with the exact Product Main issue proposal;
  • snapshot Linear issue 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 the 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 change records, and ANU-22'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 that would require 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-28T16:13:13.2017932Z;
  • 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-22 overview, ImplementationPlan, process workflow, CLI bootstrap guidance, process index, changes index, ImplementationLog, and CompletionReport as applicable.
  • Because the planned source delta is limited to Markdown and skill metadata, do not run pnpm lint, pnpm typecheck, pnpm test:int, or pnpm test:e2e. Record that intentional skip with the exact changed-file evidence. If any non-document executable CMS file enters the diff, run the required CMS checks for its affected boundary.

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, migration, authentication/authorization, privacy, security, billing, deployment architecture, or release-coordination change.
  • No CMS runtime, route, server action, collection, Payload schema, migration, database, workspace/auth, billing, PresentationConfig, Mastra, RAG, worker, Playwright, dependency, or generated-file change.
  • No compatibility alias for Direct Maintenance or anuva maintenance.
  • Before merge, rollback is removal of the new repository-change skill and ANU-22 records plus restoration of the 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 16:22 UTC. The earlier approval of anuva work start ANU-22 --confirm did not authorize implementation; this subsequent approval did.