Skip to content

Change Brief: Repository-scoped change workflow

Identity

  • Change ID: 2026-07-28-anu-19-repository-change-workflow
  • Source Linear change issue: ANU-19
  • Priority: Medium
  • Owner: Product Main coordination with repository-local workflow delivery
  • Status: Product plan approved

User outcome

Routine changes owned by one Anuva repository can enter a complete, Linear-backed, plan-first delivery workflow without requiring a Product Main change intake for each task. The user retains explicit control over issue creation/start, the generated implementation plan, PR readiness and merge, branch cleanup, base synchronization, and Linear completion.

Current behavior

  • $anuva-direct-maintenance is explicit-only, issue-free, and limited to narrow behavior-preserving maintenance.
  • Direct Maintenance uses codex/maintenance-* branches and maintenance-specific PR operations. It creates no Linear record, implementation plan, log, or completion report.
  • Normal repository implementation starts from a Ready child created from an approved Product Main manifest. Validation and completion assume a Product Main parent, Product Main source links, and one implementation-repository PR.
  • Repository-local requests that are too broad for Direct Maintenance incur a full Product Main intake even when no product-level or cross-repository decision is required.
  • Product Main documentation impact is reported by implementation repositories, but the repository workflow cannot deliver a bounded Product Main documentation companion PR as part of the same issue.

Target behavior

Read-only eligibility preflight

  • Introduce $anuva-repository-change in Product Main, Bento, CMS, Python, and Unity.
  • Allow implicit selection from a request to change the current repository. Explicit invocation remains supported.
  • Treat implicit selection as workflow routing only. It does not approve any state-changing command or generated plan.
  • Before creating a standalone Linear issue, branch, change folder, ImplementationPlan, or PR, inspect the request, repository ownership, likely affected files, active contracts, repository instructions, and relevant Product Main documentation.
  • Assign exactly one Product Main documentation disposition: Not required, Required, or Escalate.
  • Use Not required only when Product Main remains accurate and record the evidence in the proposed intake.
  • Use Required only when Product Main needs bounded documentation synchronization with behavior already owned by the invoking repository.
  • Use Escalate for product decisions, shared contracts, multi-implementation-repository work, migrations, authentication or authorization, privacy, security, billing, deployment architecture, release coordination, or any uncertainty about repository ownership or Product Main decision impact.
  • Fail closed on Escalate: create no standalone Linear issue, branch, change artifacts, or PR. Return the escalation reasons and exact proposed Product Main issue title, state, priority, label, outcome, constraints, non-goals, and source context so the normal Product Main intake can begin.

Standalone Linear intake

  • Permit intake only after the preflight returns Not required or Required.
  • Before mutation, show the title, complete description, priority, current repository label, generated idempotency key, preflight disposition and evidence, and planned branch effect.
  • A confirmed allowlisted operation creates or reuses one top-level Linear issue in In Progress with exactly one configured repository label.
  • Mark the issue as a standalone repository change through a versioned, CLI-managed description marker. Never infer this type only from title, parent absence, or status.
  • Create or switch to codex/<issue-id>-<slug> from the configured base after Linear returns the issue identifier.
  • Make partial creation recoverable: a retry with the same intake and idempotency key reuses the issue and reconciles the branch instead of creating a duplicate.

Plan-first implementation

  • Reuse the existing repository implementation lifecycle after intake normalization.
  • Revalidate the approved preflight disposition before writing change artifacts. A newly discovered escalation condition stops before artifact creation.
  • Create and preview the issue change-folder index and ImplementationPlan.md before implementation.
  • End the turn after presenting the plan. Require a subsequent explicit approval of the exact current plan.
  • After approval, implement only repository-owned scope; maintain ImplementationLog.md, durable behavior/process documentation, tests, and CompletionReport.md.
  • A material plan change repeats the preview and approval gate.
  • Create a linked draft repository PR and move the issue from In Progress to In Review.

Product Main documentation delivery

  • Carry the preflight Not required or Required disposition and its evidence into the ImplementationPlan and CompletionReport.
  • Reconfirm at completion that the disposition is still accurate.
  • For Required, create a managed Product Main companion branch and draft PR linked to the same standalone issue. Preview those pages through the Product Main MkDocs instance.
  • Keep the standalone issue labeled for the invoking repository. The companion documentation PR does not create a second Linear issue or change repository ownership.
  • Treat a later discovery that Product Main must define or revise a decision as a planning defect. Stop immediately, create no further artifacts or delivery mutations, and require explicit recovery direction; never silently convert the repository issue into a Product Main change.

Review and completion

  • Generalize the existing review skill so it accepts either a Product Main-created implementation child or a marked standalone repository issue.
  • Inspect the Linear contract, approved plan, implementation log, completion report, complete repository PR diff, optional Product Main docs PR diff, reviews, required checks, and exact docs previews.
  • Present the complete evidence and all intended mutations, then pause for explicit completion approval.
  • After approval, ready the required draft PRs and perform one guarded, idempotent repository-change completion operation.
  • Merge the implementation PR first. When required, merge the Product Main documentation PR second so canonical Product Main source never lands ahead of implementation.
  • Fast-forward each affected local base, delete every managed source branch locally and remotely, verify cleanup, record completion evidence, and then move Linear from In Review to Done.
  • If any merge, cleanup, base update, docs delivery, or Linear update partially fails, keep or return the issue to its truthful non-Done state and reconcile by retrying the identical completion operation.

Issue-free maintenance removal

  • Remove anuva-direct-maintenance, its discovery metadata, and its copies from Product Main, Bento, CMS, Python, and Unity.
  • Remove anuva-cross-repo-maintenance and its discovery metadata from Product Main. Multi-repository work returns to the normal Product Main intake.
  • Remove the complete anuva maintenance CLI namespace, implementation, help surface, tests, and documentation. Provide no deprecated command, compatibility alias, or recovery-only path.
  • Remove issue-free maintenance authorization and terminology from active AGENTS policy, skills catalogs, prompts, templates, workflow documentation, and repository bootstrap guidance.
  • Preserve immutable Git and GitHub history and ANU-19's removal record; do not rewrite historical commits or merged PRs.
  • Activate anuva-repository-change only after its guarded replacement CLI and repository policy are verified.

Known constraints

  • Linear remains the durable source for scope, priority, repository ownership, delivery links, and status.
  • GitHub remains the source for branches, PRs, reviews, checks, merge state, and remote cleanup.
  • Repository Markdown remains the durable plan, implementation log, documentation, and completion evidence.
  • The Anuva CLI remains an allowlisted executor. It must not accept arbitrary shell commands, generic workflow definitions, or untyped Linear payloads.
  • The standalone issue description must contain complete Scope, Acceptance, Docs, and Verification sections before creation.
  • The standalone intake must contain a completed read-only preflight with Not required or Required; the CLI rejects Escalate and missing evidence.
  • One standalone issue owns one implementation repository PR and zero or one bounded Product Main documentation companion PR.
  • Product Main may itself invoke the repository-change workflow. Its standalone marker must distinguish that issue from a top-level product-change parent.
  • Existing Product Main child workflows must remain compatible and retain their Ready-to-In Progress start transition.
  • Documentation changes must follow each repository's strict, branch-specific preview contract.
  • Repository worktrees must be clean or already on the exact managed branch before branch creation or switching.
  • A pre-removal audit must confirm that no open maintenance PR or local/remote codex/maintenance-* branch requires recovery. The 2026-07-28 audit found none across the five configured repositories.

Non-goals

  • Removing the Product Main change workflow.
  • Automatically converting a repository request into cross-repository product scope.
  • Creating a standalone issue, branch, change artifact, or PR merely to record an Escalate disposition.
  • Allowing implicit requests to approve issue creation, plans, commits, pushes, merges, branch deletion, or Linear completion.
  • Allowing more than one implementation repository under one standalone issue.
  • Using a Product Main docs companion PR to introduce a new decision or shared contract.
  • Enabling GitHub-driven Linear status transitions, GitHub Issues, GitHub Projects, YAML execution, Codex Goals, Symphony, or autonomous browser tests.
  • Making the Anuva CLI a general workflow engine or arbitrary shell wrapper.
  • Rewriting immutable Git history or merged GitHub PR records that document the removed workflow.

Product acceptance criteria

  • [ ] A matching repository-local request can select $anuva-repository-change without explicit skill invocation.
  • [ ] A read-only preflight inspects repository ownership, likely affected files, active contracts, and relevant Product Main documentation before any standalone issue, branch, artifact, or PR exists.
  • [ ] Escalate returns the reasons and exact proposed Product Main intake while producing no repository-change mutation or artifact.
  • [ ] The skill presents the complete standalone intake and exact mutation only for Not required or Required.
  • [ ] One confirmed, idempotent operation creates or reuses an In Progress issue with the exact current repository label and creates or restores the managed issue branch.
  • [ ] The CLI distinguishes a marked standalone repository issue from both a Product Main parent and a Product Main-created implementation child.
  • [ ] The generated ImplementationPlan receives a separate, subsequent explicit approval before code, configuration, tests, durable docs, log, report, or PR creation.
  • [ ] Existing implementation children and standalone repository issues reuse the same normalized implementation procedure where their lifecycle agrees.
  • [ ] Repository PR creation links the issue and moves it to In Review.
  • [ ] The ImplementationPlan and CompletionReport carry and revalidate the preflight Product Main documentation disposition and evidence.
  • [ ] A required bounded Product Main documentation update is previewed and delivered through a companion PR linked to the same issue.
  • [ ] Product-level or cross-repository documentation needs stop and escalate instead of being smuggled through the companion path.
  • [ ] Completion approval covers all required PR readiness, merges, local/remote branch deletion, local base synchronization, evidence recording, and the In Review-to-Done transition.
  • [ ] Implementation merges before Product Main documentation, and Linear cannot become Done until all required PRs and cleanup are verified.
  • [ ] Repeating the same intake or completion command reconciles partial success without duplicate issues, PRs, merges, or status transitions.
  • [ ] Existing Product Main-created child workflows continue to pass unchanged.
  • [ ] anuva-direct-maintenance and anuva-cross-repo-maintenance, including discovery metadata and repository copies, are deleted.
  • [ ] The anuva maintenance CLI namespace, implementation, help entries, tests, and active documentation are deleted with no alias or recovery command.
  • [ ] Outside ANU-19's removal record and immutable Git/GitHub history, active repository content contains no issue-free maintenance workflow or authorization.
  • [ ] Product Main, Bento, CMS, Python, and Unity contain aligned repository policy, skills, metadata, and local workflow documentation.
  • [ ] Product Main CLI tests, skill validation, strict documentation builds, and repository-local verification all pass.

Canonical contracts

Issue kinds

Kind Parent Initial state Repository label Creation path
Product change None Backlog Product Main Manual Linear intake followed by guarded change start
Implementation child Product change Ready Owning repository Approved Product Main manifest
Standalone repository change None In Progress Invoking repository Guarded repository-change intake

A versioned managed marker is authoritative for the third kind. Parent absence alone is insufficient because Product Main change parents are also top-level.

Required standalone issue content

The intake schema requires:

  • schema version and stable client key;
  • title, priority, current repository, and summary;
  • Scope, Acceptance, Docs, and Verification sections;
  • explicit eligibility rationale and escalation checks; and
  • a completed Not required or Required Product Main documentation preflight with evidence.

The CLI adds only managed identity and delivery blocks. It must not rewrite the user-approved scope or acceptance contract. It rejects Escalate because that outcome has no standalone intake.

The Linear description may contain these separate CLI-managed links:

  • implementation pull request;
  • optional Product Main documentation pull request;
  • implementation documentation source and preview;
  • optional Product Main documentation source and preview; and
  • completion report.

The implementation PR remains the primary PR for repository ownership and Linear/GitHub integration. The Product Main link is a companion delivery record.

Compatibility and migration

  • Existing implementation children continue to use linear-implement-issue, anuva-implement-issue, anuva pr create, and the child completion path.
  • The shared implementation and review skills normalize both issue kinds but preserve child-only Product Main link and parent validation.
  • Standalone issues require the new marker and cannot be fabricated by changing the status or labels of an arbitrary top-level issue.
  • The pre-removal audit found no open maintenance PR or surviving local/remote maintenance branch, so no compatibility or recovery surface is required.
  • Historical merged maintenance PRs remain immutable delivery history and are not retroactively entered into Linear.
  • Rollout merges Product Main first. Repository skill copies activate only after the CLI foundation is merged and locally available.
  • If rollout is interrupted, repositories that have not merged their child must not start new issue-free work or copy only part of the replacement workflow.

Failure, cancellation, and recovery behavior

  • An Escalate preflight performs no mutation and needs no repository cleanup. Its recovery path is the normal Product Main intake described in the returned issue proposal.
  • Duplicate intake retries reuse the issue selected by the stable managed marker.
  • If Linear creation succeeds but branch creation fails, return the issue ID and retry command; never create another issue.
  • If a branch exists with incompatible ancestry or unrelated changes, stop without switching or mutating Linear.
  • If PR creation succeeds but Linear linkage fails, return the PR URL and a named recovery operation.
  • If the repository PR merges but Product Main docs fail, keep the issue In Review and retry completion after repairing only the companion delivery.
  • If branches clean up but Linear completion fails, retry completion; verify the already-merged PRs and absent branches before moving Linear.
  • If genuinely new evidence reveals an escalation condition after intake, implementation or delivery stops immediately. Preserve the truthful Linear, branch, artifact, and PR state and request explicit recovery direction; this exceptional path must not be presented as successful preflight behavior.
  • Cancellation never deletes unmerged work automatically. Record the reason and use a separate explicit cancellation operation only if one is introduced and approved later.

Security and privacy

  • Treat Linear issue content as untrusted text; never interpolate it into shell expressions.
  • Validate repository keys, label IDs, paths, URLs, issue identifiers, branch prefixes, and PR repository/base/head identities before mutation.
  • Keep secrets, environment values, tokens, cookies, signed URLs, and local machine paths out of Linear descriptions and PR bodies except for explicitly required local completion-report paths passed to the CLI.
  • Preserve exact GitHub repository and branch protection checks.
  • Refuse cross-fork or cross-repository PR heads for cleanup.
  • Product Main docs synchronization may touch only configured Product Main paths selected by the approved implementation plan.

Documentation impact

  • Product Main updates AGENTS policy, the skills catalog, Linear workflow, Product Change workflow, review/completion workflow, prompt/skill/CLI model, Anuva CLI contract and implementation plan, repository registry/process guidance, relevant prompts/templates, and this change folder.
  • Product Main adds the canonical anuva-repository-change skill and removes both issue-free maintenance skills plus the maintenance CLI implementation and tests.
  • Each implementation repository updates AGENTS policy, local docs/process/ChangeWorkflow.md, bootstrap CLI documentation where present, shared implementation/review skill copies, and skill discovery metadata.
  • Every repository deletes the old skill and active references only when its replacement and required CLI are verified.

Approval record

  • Plan reviewed by: Girish
  • Approved at: 2026-07-28 08:01 UTC
  • Approval notes: Approved as revised, including the read-only preflight before any standalone mutation or artifact, no-side-effect Escalate outcome, standalone SDK-backed intake only for Not required or Required, optional bounded Product Main documentation companion delivery, five repository implementation issues with Product Main first, and complete removal of both issue-free maintenance skills and the anuva maintenance CLI with no compatibility alias.