Skip to content

Implementation Plan: ANU-21 - Adopt Repository-change Workflow in Anuva Bento

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 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 Bento ownership, upstream ancestry and synchronization, provenance, licensing, artifact, security, and verification rules.
  • Add the ANU-21 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-21, Adopt repository-change workflow in Anuva Bento.
  • 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-bento.
  • 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: Bento downstream main at 8dd5c4ff8a8a9760f845b2fc43c34ae6a940e07e.
  • 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-21 changes only Bento-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, upstream release coordination, security/privacy concern, deployment change, or ownership uncertainty stops work and returns to Product Main.
  • The pre-existing untracked __pycache__/ directory is outside ANU-21 and will remain untouched.

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 Bento-specific additions to the canonical skills:
  • run the upstream install/build/convergence baseline and focused downstream checks when executable Bento files change;
  • for process-only changes, explicitly record why the product build was not run;
  • preserve upstream ancestry, disabled upstream pushes, tagged-release sync policy, license/notices, artifact, and hard-offline verification where affected;
  • validate recursive indexes and strict Bento 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.

3. Align Bento 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 Bento escalation boundaries explicit:
  • product decisions and shared cross-repository contracts;
  • more than one implementation repository;
  • upstream release or synchronization work;
  • migrations, authentication/authorization, privacy, security, billing, deployment architecture, and release coordination; and
  • uncertain repository ownership.
  • Preserve the current repository role, upstream boundary, baseline commands, provenance, licensing, notices, artifact, and downstream 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.
  • Do not change Bento runtime, schemas, adapters, templates, packages, build entries, upstream source, license, or notices.

4. Record and deliver the implementation

  • After explicit approval of this exact plan, create:
  • ImplementationLog.md with timestamps, source commit identities, exact edits, commands, tool versions, network behavior, skipped checks, and no-side-effect evidence; and
  • CompletionReport.md mapping every ANU-21 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-21 --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/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-21 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 Bento-specific verification and managed-auth differences; and
  • confirm the diff contains no executable Bento, upstream, runtime, schema, package, template, artifact, license, or notice 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 succeeds while the removed anuva maintenance namespace is unavailable.
  • Escalation and approval boundaries:
  • forward-test a natural Bento request that requires upstream-release or shared-contract coordination 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-21'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 --since 2026-07-28T14:27:03.7745779Z;
  • anuva docs links;
  • compare every changed live page with the fresh strict MkDocs build; and
  • return exact HTTPS preview URLs for the ANU-21 overview, ImplementationPlan, process workflow, CLI bootstrap guidance, changes index, ImplementationLog, and CompletionReport as applicable.
  • Because the planned source delta is limited to Markdown and skill metadata, do not run npm ci, the upstream build, the Windows single-file build, convergence tests, downstream typechecks, editor/player tests, template checks, or packaging checks. Record that intentional skip with the exact changed-file evidence. If an executable Bento file enters the diff, run the full AGENTS.md baseline and every focused affected downstream check.

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, upstream release or sync, package/release coordination, migration, authentication/authorization, privacy, security, billing, or deployment architecture change.
  • No Bento editor/player behavior, document contract, compatibility metadata, template family, semantic binding, build entry, dependency, runtime artifact, source package, provenance, license, or notice change.
  • No compatibility alias for Direct Maintenance or anuva maintenance.
  • Before merge, rollback is removal of the new repository-change skill and ANU-21 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 14:37 UTC. The earlier approval of anuva work start ANU-21 --confirm did not authorize implementation; this subsequent approval did.