Skip to content

Implementation Plan: ANU-20 - Implement repository-change CLI and canonical workflow

References

  • Linear issue: ANU-20
  • Product Main change docs: ANU-19
  • Repository: anuva-main-video-creator
  • Branch: codex/anu-20-implement-repository-change-cli-and-canonical-wo
  • Product Main documentation disposition: Required
  • Disposition evidence: ANU-20 changes the Anuva development workflow, CLI contract, skill catalog, repository policy, prompts, templates, and implementation/review guidance owned by Product Main. The bounded pages and root policy files are enumerated below. No product behavior or implementation-repository code is in scope.

Scope and non-goals

Scope

  1. Add a typed, versioned standalone repository-change intake that can only represent a completed Not required or Required preflight.
  2. Add allowlisted CLI operations that create or reconcile one standalone Linear issue and its repository branch, manage at most one bounded Product Main documentation companion, and complete all required delivery idempotently.
  3. Normalize and validate three distinct Linear issue kinds: product-change, implementation-child, and standalone-repository-change.
  4. Generalize repository PR creation, review, and completion where child and standalone lifecycles intentionally agree without weakening Product Main child validation.
  5. Add the canonical implicitly selectable anuva-repository-change skill and Product Main copies of the shared implementation and review skills needed to execute the common plan-first lifecycle.
  6. Remove anuva-direct-maintenance, anuva-cross-repo-maintenance, and the complete anuva maintenance CLI namespace, implementation, tests, help, and active workflow documentation without a compatibility alias.
  7. Align Product Main policy, prompts, templates, engineering documentation, navigation, and indexes with the replacement workflow.

Non-goals

  • A generic Linear issue creation API or arbitrary Linear payload support.
  • Automatic approval of issue creation, an Implementation Plan, PR readiness, merge, cleanup, or Linear completion.
  • More than one implementation repository or implementation PR per standalone issue.
  • Product decisions, shared-contract changes, or application/CLI changes delivered through the Product Main documentation companion.
  • Changes to Product Main parent planning/decision/completion semantics.
  • Rewriting historical Git commits or merged GitHub pull requests.
  • Adopting the skill in Bento, CMS, Python, or Unity; ANU-21 through ANU-24 own those repository-local changes after ANU-20 is Done.

Current repository behavior

  • src/adapters/linear.ts recognizes parent/child relationships and extracts PR and Product Main links, but does not expose an authoritative issue kind or a standalone repository-change marker.
  • anuva linear change create-implementation-issues creates only Product Main children in Ready, while anuva work start moves those children to In Progress and creates their managed branch.
  • anuva pr create can link a PR for a repository-labeled issue, but its validation does not distinguish a child, a Product Main parent, and a marked standalone issue. anuva pr merge intentionally accepts children only.
  • Product Main phase commands reject children by checking parent, but a Product Main-labeled standalone top-level issue would currently be indistinguishable from a Product Main parent.
  • The CLI has no bounded Product Main documentation companion or ordered multi-PR completion operation.
  • anuva maintenance provides an issue-free codex/maintenance-* branch and PR path, and the two maintenance skills authorize that path explicitly.
  • Product Main does not currently install the shared linear-implement-issue, anuva-implement-issue, or anuva-review-and-complete-pr skill entry points used by implementation repositories.
  • The completed pre-removal audit found no open maintenance PR and no surviving local or remote codex/maintenance-* branch across the five configured repositories, so removal needs no recovery command or alias.

Planned command and data contracts

Read-only preflight boundary

anuva-repository-change owns the open-ended, read-only judgment. Before any standalone issue, branch, change folder, plan, or PR, it will inspect:

  • the request and expected outcome;
  • the current repository's AGENTS.md, ownership, and likely affected files;
  • active repository contracts and relevant Product Main pages; and
  • escalation triggers from the approved ANU-19 contract.

It returns exactly Not required, Required, or Escalate.

Escalate is a terminal, no-side-effect response containing the reasons and an exact Product Main issue proposal. It has no serializable mutating intake: the CLI schema accepts only not-required and required. This makes an accidental Escalate mutation fail schema validation before any adapter call.

Intake schema and marker

Add src/schemas/repository-change.ts with schema version 1. The JSON intake contains:

  • schemaVersion: 1;
  • a generated, retry-stable idempotencyKey;
  • title and Linear priority;
  • complete scope, acceptance, docs, and verification inputs;
  • productMainDocs.disposition as not-required or required;
  • non-empty preflight evidence;
  • for required, a non-empty, bounded list of Product Main documentation paths; and
  • for not-required, an empty Product Main path list.

The current configured repository is always resolved by the CLI and is not a caller-selectable target.

The Linear description will contain the rendered contract plus the authoritative marker:

<!-- anuva:repository-change:v1;repository:<repository-key>;idempotency-key:<key> -->

The marker is used only for this workflow. A retry searches for the exact marker, verifies the title, priority, label, normalized contract, and state, then reuses the issue. A marker collision or incompatible existing issue fails closed.

CLI surface

Add one narrow command group:

anuva repository-change start <intake-json> --dry-run
anuva repository-change start <intake-json> --confirm
anuva repository-change docs start <issue-id> --plan <absolute-plan-path> --dry-run
anuva repository-change docs start <issue-id> --plan <absolute-plan-path> --confirm
anuva repository-change docs pr create <issue-id> --plan <absolute-plan-path> --preview <url> --dry-run
anuva repository-change docs pr create <issue-id> --plan <absolute-plan-path> --preview <url> --confirm
anuva repository-change docs pr ready <issue-id> --dry-run
anuva repository-change docs pr ready <issue-id> --confirm
anuva repository-change complete <issue-id> --report <absolute-report-path> --dry-run
anuva repository-change complete <issue-id> --report <absolute-report-path> --confirm

start dry-runs the exact issue, label, marker, state, and branch effects. On confirmation it creates or reuses one top-level issue directly in In Progress with exactly the current repository label, then creates, restores, or switches to codex/<issue-id>-<slug>. If issue creation succeeds but branch reconciliation fails, the identical command reuses the marked issue.

The existing anuva pr create <issue-id> --draft and anuva pr ready <issue-id> operations remain the implementation-PR surface. They will accept an implementation child or marked standalone issue and reject a Product Main parent or ambiguous top-level issue.

The docs commands are valid only for a marked standalone issue whose recorded disposition is Required and whose absolute Implementation Plan records explicit approval. They use the deterministic Product Main branch codex/<issue-id>-<slug>-product-main-docs, permit only the exact recorded documentation paths plus necessary nearest index.md and mkdocs.yml navigation entries, require strict Product Main preview evidence, create at most one draft PR, and store it as Product Main Documentation Pull Request. They reject application code, Anuva CLI code, decisions, shared contracts, and process redesign.

complete is the only standalone merge/Done operation. It requires an absolute Completion Report, a clean affected worktree, a reviewable implementation PR, and, for Required, a reviewable companion docs PR with strict preview evidence. After explicit completion approval has been obtained by the review skill, it:

  1. merges and verifies the implementation PR;
  2. fast-forwards its configured local base and deletes/verifies its local and remote source branches;
  3. when required, merges and verifies the Product Main docs PR;
  4. fast-forwards Product Main and deletes/verifies the companion branches;
  5. records managed delivery, preview, and Completion Report evidence; and
  6. moves the standalone issue from In Review to Done.

Each step re-inspects current state. A retry skips verified effects and resumes at the first incomplete effect; the issue cannot become Done while a required PR, base synchronization, branch cleanup, or evidence update is incomplete.

Issue-kind classification

Add a fail-closed classifier used by all lifecycle commands:

Kind Required shape Permitted lifecycle
product-change No parent, no standalone marker, Product Main label Existing linear change, work change, and pr change phases
implementation-child Parent present, no standalone marker, repository label, Product Main source/preview contract Existing Ready-to-In Progress child lifecycle and pr merge
standalone-repository-change No parent, valid versioned marker, exactly one current repository label, complete local intake repository-change start, common plan/PR path, and repository-change complete

A parent plus standalone marker, an unsupported marker version, multiple repository labels, or an unmarked non-Product-Main top-level issue is invalid for managed delivery. Product Main phase commands will require product-change; child merge will require implementation-child; standalone completion will require standalone-repository-change.

Planned changes

Acceptance check Code area Test/evidence Docs
Escalate cannot create an artifact or mutation New canonical skill; src/schemas/repository-change.ts; CLI parsing before adapters Schema rejects escalate; skill scenario verifies unchanged Linear/Git/docs/GitHub state AGENTS.md; Skills.md; LinearWorkflow.md; prompts
Allowed preflight is complete and bounded Repository-change schema and renderer Missing evidence, sections, disposition, or required paths fail before mutation Intake template and CLI reference
Intake creates/reuses one marked In Progress issue with current repository label src/adapters/linear.ts; new src/commands/repository-change/index.ts SDK-adapter tests for create, exact label/state, marker reuse, and collision rejection AnuvaCli.md; workflow docs
Branch creation is guarded and retryable New command reusing Git and safe-switch primitives Integration tests for create, restore, dirty worktree refusal, and issue-created/branch-failed retry CLI implementation plan
Three issue kinds cannot cross boundaries Linear normalization/classifier; work, PR, and Product Main phase guards Matrix tests for valid kinds, ambiguous shapes, unsupported marker, and every wrong command family Linear and product-change workflows
Existing children retain their validation src/commands/work/start.ts; src/commands/pr/index.ts; Linear transitions Existing tests plus child-specific source/preview, parent, blocker, Ready/In Progress, and merge tests Implementation workflow
Common plan-first flow supports standalone issues Canonical skills and common PR create/ready validation Skill validation and command tests for child/standalone acceptance and parent rejection Prompts, templates, skill catalog
Repository PR is draft, linked, and moves In Progress to In Review src/commands/pr/index.ts; src/adapters/linear.ts PR creation/link verification and partial Linear update retry tests PR and review docs
Required creates at most one bounded Product Main docs companion New docs start/create/ready operations; GitHub and Linear managed-block helpers Path allowlist, deterministic branch, duplicate PR reuse, wrong repo/base/head, code-path, and preview rejection tests CLI and docs workflow
Not required forbids a companion Schema and docs command guards Unit and command tests Intake template
Later product/shared-contract discovery stops delivery Canonical implementation/review skills Skill scenario asserts pause and no further mutation Workflow and skill docs
Completion approval covers all effects Canonical review skill; completion dry-run plan Skill validation and dry-run action snapshot Review and completion workflow
Implementation merges before docs and Done is last New completion command reusing reviewability, guarded merge, cleanup, and Linear transition helpers Ordered adapter-call tests and state assertions Review and completion workflow
Completion retry reconciles partial effects Completion state inspection and managed Linear blocks Tests at implementation merge, implementation cleanup, docs merge, docs cleanup, evidence write, and Linear transition failure boundaries CLI recovery guidance
Maintenance workflow is absent with no alias Delete maintenance CLI module/import/group/tests and both maintenance skills/metadata CLI help/unknown-command tests; active-reference searches; no maintenance branch/PR audit All active policy/workflow/catalog pages
Product Main owns canonical reusable skills Add repository-change, implementation, and review skill directories with metadata Skill-creator validator and exact catalog/install-matrix checks Skills.md; PromptSkillCliModel.md
Documentation is complete and reviewable Product Main docs and root policy updates listed below Recursive index validation, strict MkDocs wait, link checks ANU-20 Implementation Log and Completion Report after approval

File-level implementation

Schemas and Linear

  • Add src/schemas/repository-change.ts for intake parsing, disposition/path invariants, marker construction/parsing, and stable description rendering.
  • Extend src/adapters/linear.ts with explicit issue-kind classification, standalone issue create/reuse, repository label cardinality checks, companion PR/preview managed links, and completion evidence updates.
  • Keep src/schemas/implementation-issues.ts and createImplementationIssues parent/child-specific.

Commands and CLI

  • Add src/commands/repository-change/index.ts for start, docs companion, and ordered completion planning/execution.
  • Reuse src/commands/pr/cleanup.ts, guarded GitHub head-OID merge, reviewability checks, locks, receipts, repository resolution, and safe branch switching.
  • Update src/commands/pr/index.ts and src/commands/work/start.ts to use explicit issue kinds while keeping child and Product Main phase rules separate.
  • Update src/cli.ts to register repository-change and remove maintenance.
  • Delete src/commands/maintenance/index.ts.

Tests

  • Add tests/unit/repository-change.test.ts for schema invariants, marker round-trips, issue classification, allowed paths, ordering, and recovery decisions.
  • Add tests/integration/repository-change.test.ts with isolated Git fixtures and controlled Linear/GitHub adapter seams for intake, branch recovery, companion docs, completion ordering, and partial retry boundaries.
  • Extend tests/unit/change-workflow.test.ts for strict child, parent, and standalone command routing.
  • Extend tests/integration/cli.test.ts for the new help surface, confirmation boundaries, and complete absence of maintenance.
  • Extend tests/integration/pr-cleanup.test.ts only where two-repository completion needs additional idempotent cleanup evidence.
  • Delete tests/unit/maintenance.test.ts and tests/integration/maintenance.test.ts; rename maintenance-only checkpoint fixture branch names in tests/integration/work-checkpoint.test.ts so the removed namespace does not remain as active test vocabulary.

Skills and metadata

  • Add .agents/skills/anuva/anuva-repository-change/ as the canonical, implicitly selectable entry point. It performs preflight, emits the exact escalation proposal or standalone intake, asks for issue/start confirmation, and then invokes the common plan-first workflow.
  • Add Product Main copies of .agents/skills/anuva/linear-implement-issue/, .agents/skills/anuva/anuva-implement-issue/, and .agents/skills/anuva/anuva-review-and-complete-pr/.
  • Generalize those contracts to accept a validated implementation child or marked standalone issue while retaining child Product Main-link checks, repository-specific verification routing, the mandatory post-plan pause, and the independent completion approval.
  • Add/update each skill's agents/openai.yaml discovery metadata and validate all changed skills with the skill-creator validator.
  • Delete .agents/skills/anuva/anuva-direct-maintenance/ and .agents/skills/anuva/anuva-cross-repo-maintenance/, including metadata.

Product Main documentation and policy

Update the following active Product Main surfaces:

  • AGENTS.md and README.md;
  • docs/engineering/AgentInstructions.md;
  • docs/engineering/AnuvaCli.md;
  • docs/engineering/CodexDevelopmentProcess.md;
  • docs/engineering/LinearWorkflow.md;
  • docs/engineering/ProductChangeWorkflow.md;
  • docs/engineering/PromptSkillCliModel.md;
  • docs/engineering/Skills.md;
  • docs/engineering/index.md;
  • docs/development/ImplementationRepositoryChanges.md;
  • docs/development/ImplementationWorkflow.md;
  • docs/development/ReviewAndCompletionWorkflow.md;
  • docs/cli-implementation/index.md;
  • docs/cli-implementation/cli-implementation-plan.md;
  • docs/prompts/ImplementCmsIssue.md;
  • docs/prompts/ReviewAndCompletePR.md;
  • docs/template-library/ImplementationPlan_Template.md;
  • affected documentation indexes and mkdocs.yml.

ANU-19 remains the explicit removal record. Generic uses of the English word “maintenance” that describe dependency versions or long-term software upkeep are not workflow references and will not be rewritten. Outside ANU-19 and immutable Git/GitHub history, searches must find no active authorization, command, branch namespace, skill, or help reference for the removed workflow.

After implementation approval, create and maintain in this folder:

  • ImplementationLog.md, recording actual decisions, files, deviations, and command receipts; and
  • CompletionReport.md, mapping every acceptance check to exact test, preview, PR, cleanup, and Linear evidence.

Contracts and dependencies

  • ANU-19's merged planning PR is the authoritative product contract.
  • ANU-20 is an implementation child and continues through the existing child lifecycle; the new standalone workflow is not used to deliver itself.
  • ANU-21, ANU-22, ANU-23, and ANU-24 remain blocked until ANU-20 is Done.
  • Linear is authoritative for issue scope, repository label, priority, managed links, and state. GitHub is authoritative for PR/check/merge state. Repository Markdown is authoritative for plan and completion evidence.
  • The CLI remains an allowlisted executor and does not classify open-ended change intent.
  • One standalone issue owns exactly one implementation repository and PR and zero or one Product Main documentation PR.
  • Every mutating CLI operation retains --dry-run/--confirm, locking, redacted structured output, and receipts.

Migration, rollback, and failure handling

  • Removal is atomic within ANU-20: the new guarded command/skill surface and updated tests/docs must be present before the maintenance surface is deleted in the final patch.
  • No compatibility alias is added because the audit found no open work that depends on the old namespace.
  • Before merge, rollback is normal branch/PR abandonment with ANU-20 left truthful in In Progress or In Review.
  • A partially created standalone intake is recovered by repeating the exact intake file and idempotency key.
  • A partially created GitHub PR is recovered by inspecting the deterministic branch before creating another PR and then repairing the managed Linear link.
  • A partially completed delivery is recovered by repeating the exact repository-change complete command; already verified merges and cleanup are not repeated.
  • A late Escalate discovery is not auto-migrated. The workflow stops, records the planning defect without further delivery mutation, and requests explicit recovery direction and a normal Product Main issue.

Verification commands

Implementation verification after approval will include:

bun run typecheck
bun test
bun run src/cli.ts --help
bun run src/cli.ts repository-change --help
bun run src/cli.ts maintenance --help
rg -n "anuva-direct-maintenance|anuva-cross-repo-maintenance|anuva maintenance|codex/maintenance-|issue-free maintenance" AGENTS.md README.md .agents docs src tests
git diff --check
anuva docs validate-indexes --repository current
anuva docs ensure --repository current --confirm
anuva docs wait --repository current --file <each-changed-doc> --since <pre-edit-utc>
anuva docs links --repository current --file <each-changed-doc>

Expected special results:

  • anuva maintenance --help fails as an unknown command.
  • The active-reference search returns only the approved ANU-19 removal record or explicitly excluded immutable history.
  • Focused unit/integration tests prove preflight schema no-side-effect behavior, intake/marker idempotency, issue-kind isolation, child compatibility, companion path and PR bounds, implementation-before-docs ordering, Done-last semantics, and each supported partial-retry boundary.
  • All changed skill folders pass the skill-creator validator.
  • Strict Product Main MkDocs preview and recursive index/link checks pass.

Risks and open questions

  • The Linear SDK does not provide a caller-supplied issue idempotency key, so marker search plus exact-contract verification is the durable duplicate prevention mechanism. Tests must cover a successful issue creation followed by a branch failure.
  • Linear issue description blocks are user-visible. Managed block replacement must preserve user-authored content and reject incompatible marker edits.
  • Product Main companion work can involve a second worktree. The implementation will use configured repository paths and existing clean-worktree/branch guards; it will not hide unrelated user changes or perform destructive resets.
  • GitHub may report a merge before local cleanup or Linear update succeeds. Completion must report truthful partial state and an exact identical retry, never mark Done early.
  • If implementation requires generic Linear creation, more than one implementation repository, unattended completion, or a companion capable of changing code or decisions, ANU-20 stops and returns to ANU-19 for a decision phase.

No design question currently requires expanding the approved ANU-19 contract.

Approval

Status: Approved

Girish explicitly approved this exact previewed plan on 2026-07-28 at 12:12 UTC. A material plan change requires a new preview and approval.