Skip to content

Workflow: Plan Product Change

Use this workflow in a Product Main Codex App task when a Linear change intake issue is ready to be shaped into one or more repository implementation issues.

A repository-local request reaches this workflow only when the read-only $anuva-development:anuva-repository-change preflight returns Product Main required. The escalation response must include the exact proposed Product Main title, state, priority, label, outcome, constraints, non-goals, source context, repositories, and acceptance evidence; it creates no repository-change artifact.

Invocation

Prefer explicit skill invocation:

$anuva-development:linear-plan-change ANU-100

The skill delegates planning to $anuva-development:anuva-plan-product-change. A natural-language request such as “Plan the product change from Linear issue ANU-100” may trigger the same skill implicitly, but explicit invocation is preferred for traceability.

Required change issue fields

  • Change ID, or enough information for Product Main to assign one
  • Title
  • User outcome
  • Known constraints
  • Priority

The change issue may contain raw notes. The planning skill normalizes them; a repository BrainDump.md is not required.

Flow

flowchart TD
    Invoke["Invoke $anuva-development:linear-plan-change ANU-100"]
    Read["anuva linear issue get ANU-100 --json"]
    Start["linear change start"]
    Branch["work change start --phase planning"]
    Plan["Create ChangeBrief and RepositoryImpact"]
    Preview["anuva docs wait and return preview URLs"]
    Approval{"User approves plan?"}
    Revise["Revise durable docs"]
    Manifest["Create ImplementationIssues.md and manifest"]
    PlanPR["create, ready, merge planning PR"]
    Create["anuva linear change create-implementation-issues --confirm"]
    Ready["Implementation issues: Ready"]

    Invoke --> Read --> Start --> Branch --> Plan --> Preview --> Approval
    Approval -- "No" --> Revise --> Preview
    Approval -- "Yes" --> Manifest --> PlanPR --> Create --> Ready

Product Main artifacts

Create docs/changes/<change-id>-<slug>/ containing:

File Purpose
index.md Overview and links for every artifact in the change folder
ChangeBrief.md User outcome, current behavior, target behavior, constraints, non-goals, acceptance criteria
RepositoryImpact.md Ownership, dependencies, contract changes, sequencing, and verification by repository
ImplementationIssues.md Reviewed Linear issue titles, bodies, dependencies, and eventual issue IDs
Progress.md Current issue/PR state summarized from Linear and GitHub
CompletionReview.md Added when the change is fully reviewed and complete
Decision.md or product ADR Only when a durable cross-repository decision is required

Approval boundary

Planning may read Linear and write Markdown before approval. It must not create or change implementation issues until the user approves the product plan. At the pause, Codex must provide:

  • concise decision summary and unresolved questions;
  • exact Cloudflare preview links for every changed MkDocs page;
  • proposed repository issue split and sequencing; and
  • the exact state-changing CLI command it will run after approval.

After approval, the CLI creates, readies, and merges the planning-phase Product Main PR while leaving the parent In Progress. Only then it creates repository-scoped Linear issues, records their IDs in ImplementationIssues.md, links the Product Main docs, and moves the issues to Ready when their inputs are complete. Completion uses a fresh completion branch and PR after all children are terminal. That merge also leaves the parent In Progress; only anuva linear change complete marks it Done.

Mid-change decisions

Use the guarded decision phase when an approved plan requires a durable post-planning gate before later children may start:

  1. Require the parent to remain In Progress and the managed planning PR to be merged.
  2. Run anuva work change start <id> --phase decision --confirm.
  3. Record the proceed, revise, or stop outcome in Decision.md; update Progress.md, ImplementationIssues.md, and the change index.
  4. Validate and preview the decision pages, then pause for explicit approval.
  5. Create, ready, and merge the decision PR through anuva pr change with --phase decision.

The decision PR does not require terminal children, does not start or transition children automatically, and leaves the parent In Progress. The completion phase remains separate and unavailable until every required child is terminal.