Skip to content

Implementation Plan: ANU-23 - Adopt Repository-change Workflow in Anuva Python Server

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 Python Server ownership, localhost defaults, protocol and adapter boundaries, redaction and secret-handling rules, simulator behavior, operational guidance, and repository-specific verification.
  • Add the ANU-23 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-23, Adopt repository-change workflow in Anuva Python Server.
  • 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-python-server.
  • 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: Python Server main at 3bf4be2088004581a98c950500e617fa6be2bd40.
  • 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-23 changes only Python-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, 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 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. 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;
  • 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 Python-specific additions to the canonical skills:
  • run focused pytest and service/protocol checks when executable Python files change;
  • for process-only changes, record the exact changed-file evidence and why pytest was not run;
  • preserve worker ownership, one-active-job V1 behavior, Web App and Unity adapter boundaries, localhost defaults, simulator expectations, path safety, output validation, diagnostics, and redaction/security checks;
  • validate recursive indexes and strict Python Server MkDocs previews for documentation; 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 Python Server 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 Python Server escalation boundaries explicit:
  • product decisions and shared cross-repository contracts;
  • more than one implementation repository;
  • migrations, authentication/authorization, privacy, security, billing, deployment architecture, and release coordination; and
  • uncertain repository ownership.
  • Preserve the current worker role, package boundaries, one-active-job V1 behavior, explicit acquisition modes, Web App and Unity boundaries, simulator status, localhost bindings, secret redaction, path safety, operational verification, and external-tool limitation reporting.
  • 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 and docs/bootstrap/index.md only where their current planned-work-only wording would otherwise omit or misdescribe the repository-change path.
  • Do not change Python runtime code, worker configuration, Web App or Unity contracts, ZeroMQ messages, simulator scenarios, service behavior, dependencies, scripts, 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/runtime versions, skipped checks, and no-side-effect evidence; and
  • CompletionReport.md mapping every ANU-23 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 evidence and previews are complete, run anuva pr create ANU-23 --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;
  • docs/bootstrap/BootstrapContext.md and docs/bootstrap/index.md where required for accurate routing;
  • 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-23 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 Python-specific verification and managed-auth differences; and
  • confirm the diff contains no executable Python, worker configuration, protocol, simulator, dependency, script, 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 Python Server request that requires a protocol, security/privacy, deployment, 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-23'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-28T18:21:06.8001329Z;
  • 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-23 overview, ImplementationPlan, process workflow, CLI bootstrap guidance, bootstrap pages, changes index, ImplementationLog, and CompletionReport as applicable.
  • Because the planned source delta is limited to Markdown and skill metadata, do not run pytest. Record that intentional skip with the exact changed-file evidence. If any executable Python file enters the diff, run focused unit or integration tests for its affected boundary and all additional checks required by AGENTS.md.

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 Python worker, CLI runtime, job acquisition/preparation, workspace, manifest, validation, upload, diagnostics, monitoring, dashboard, simulator, Web App client, Unity process supervision, ZeroMQ protocol, service, config, dependency, operational script, or test change.
  • No compatibility alias for Direct Maintenance or anuva maintenance.
  • Before merge, rollback is removal of the new repository-change skill and ANU-23 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 18:29 UTC. The earlier approval of anuva work start ANU-23 --confirm did not authorize implementation; this subsequent approval did.