Linear Configuration and Workflow

Linear is Anuva's durable control plane for product change intake, Product Main handoffs, priority, dependencies, explicitly tracked repository work, workflow state, and delivery links. Routine and material repository work is issue-free by default under the Phase 4 plugin contract.

Repository-local work uses a marked standalone Linear issue only when the user explicitly requests durable tracking. The repository skill otherwise returns Routine, Material, or Product Main required; the last disposition creates no Linear, Git, documentation, or GitHub artifact and returns an exact Product Main issue proposal. Product decisions, shared contracts, multiple implementation repositories, migrations, authentication/authorization, privacy, security, billing, deployment architecture, release coordination, and uncertain ownership use the normal Product Main hierarchy below.

Team and issue hierarchy

Use one Linear team with key ANU for all product and implementation work. Repository ownership is expressed by labels rather than separate Linear teams.

The CLI distinguishes three issue kinds:

Kind	Parent	Initial state	Repository label
Product change	None	Backlog	`anuva-main-video-creator`
Implementation child	Product change	Ready	Owning repository
Standalone repository change	None	In Progress	Invoking repository

The standalone kind requires a versioned CLI-managed marker; parent absence is not sufficient because Product Main changes are also top-level. Each product change uses this hierarchy:

flowchart TD
    Change["Parent change issue\nproduct outcome"]
    Main["Product Main child\nwhen coordination code or docs change"]
    Bento["Bento child\nanuva-bento"]
    Web["CMS child\nanuvax-cms"]
    Python["Python child\nanuva-python-server"]
    Unity["Unity child\nanuva-unity-video-creator"]

    Change --> Main
    Change --> Bento
    Change --> Web
    Change --> Python
    Change --> Unity

The parent issue owns the requested user outcome, constraints, priority, and links to the Product Main change folder.
Each implementation issue is a repository-scoped child created from the approved Product Main manifest.
Create only the children required by the repository impact analysis.
Use explicit blocking relations for dependency order. Do not encode dependencies in status names or free-form labels.
Keep Linear parent and sub-issue auto-close disabled. The parent closes only after the Product Main completion review verifies the cross-repository outcome.

Status model

Configure exactly these six issue statuses:

Status	Linear category	Meaning
`Backlog`	Backlog	Captured product request that is not yet selected for active planning.
`Ready`	Unstarted	Approved implementation issue with complete inputs and satisfied blockers.
`In Progress`	Started	Product planning or repository implementation is actively underway.
`In Review`	Started	A repository PR and its completion evidence are being reviewed.
`Done`	Completed	The applicable implementation or product completion workflow passed.
`Canceled`	Canceled	Work was intentionally abandoned with its reason recorded.

Blocked is a relation, not a status. A blocked issue stays in its actual lifecycle state and appears in the Blocked view until its blocking relations are resolved.

An approval pause is also not a Linear status. The durable plan records the approval, and the interactive Codex task shows the pending mutation. Add a CLI-managed attention label later only if approval waits become difficult to find in practice.

Parent change lifecycle

flowchart LR
    Backlog["Backlog"] --> Active["In Progress\nplanning through delivery"]
    Active --> Planning["Planning PR merged\nparent unchanged"]
    Planning --> Review["Completion PR merged\nparent unchanged"]
    Review --> Done["change complete → Done"]
    Backlog --> Canceled["Canceled"]
    Active --> Canceled

The parent remains In Progress while its repository children are implemented. Completing every child does not automatically complete the parent.

linear change start is the only supported Backlog to In Progress transition for a parent. Planning and completion PR operations leave it In Progress; linear change complete performs the direct guarded transition to Done after both delivery phases and child verification.

Implementation issue lifecycle

flowchart LR
    Ready["Ready"] --> Progress["In Progress"]
    Progress --> Review["In Review"]
    Review --> Done["Done"]
    Ready --> Canceled["Canceled"]
    Progress --> Canceled
    Review --> Canceled

Only named Anuva CLI operations perform supported transitions. The CLI verifies the current state, repository, blockers, required artifacts, PR state, and completion evidence before changing Linear.

Optional standalone repository-change lifecycle

flowchart LR
    Preflight["Read-only preflight"] --> Intake["Approved intake\nIn Progress"]
    Intake --> Plan["Approved Implementation Plan"]
    Plan --> Review["Draft PR\nIn Review"]
    Review --> Done["Approved completion\nDone"]
    Preflight --> Escalate["Escalate\nno artifacts"]

The confirmed intake creates or reuses the marked issue directly in In Progress and reconciles its managed branch. Completion merges implementation first, optionally merges one bounded Product Main docs companion, synchronizes bases, deletes managed branches, records evidence, and moves Linear Done last.

Issue templates

Keep template administration small.

Anuva Change Intake

Use one default change-intake template with:

title;
user outcome;
current and target behavior when known;
known constraints and non-goals;
priority; and
source material or related links.

The default state is Backlog. Raw notes are acceptable; Product Main planning normalizes them into durable change documentation.

Quick Defect

Add this optional template only if defect capture is common. Include observed and expected behavior, reproduction, user impact, environment, and evidence.

Do not maintain a manual implementation-issue template. The validated Product Main manifest is the schema for children. Standalone issues use the versioned repository-change intake schema; it is not exposed as a generic issue creator.

Priorities

Apply priority consistently:

Priority	Use
Urgent	Active production, security, or data-loss incident requiring immediate action.
High	Blocks the current committed product outcome or another repository.
Medium	Normal planned work and the default for accepted changes.
Low	Useful opportunistic work that should not displace committed outcomes.
No priority	Untriaged backlog capture only.

Due dates represent real external commitments only. Do not add estimates until they will inform a concrete capacity or sequencing decision.

Labels

Start with one required label group: Repository. Use the exact repository names as labels:

anuva-main-video-creator
anuva-bento
anuvax-cms
anuva-python-server
anuva-unity-video-creator

Apply exactly one repository label to each implementation child or standalone issue. Do not create labels that duplicate status, priority, assignee, cycle, or approval state. Templates and top-level/sub-issue filters are sufficient for the initial views; add a Kind label group only after a demonstrated reporting need.

Projects, initiatives, and cycles

Do not create a Linear Project for every product change. The parent issue and Product Main change folder already provide that unit of coordination, while a Linear Project introduces a separately maintained lifecycle.

Create a Project only for a larger outcome with multiple independent parent changes or a meaningful target date, such as a private beta or billing launch. Do not use Initiatives until multiple active projects need goal-level rollup.

Keep Cycles disabled initially. If a fixed delivery cadence later becomes useful, enable two-week cycles and auto-add active issues instead of assigning cycles manually. Reconsider this only after enough completed work exists to make capacity history useful.

Saved views

Create and favorite these workspace views:

View	Filter and presentation
`Next`	`Ready`, ordered by priority and grouped by Repository. Make this the default view.
`Doing`	`In Progress` or `In Review`, grouped by status and Repository.
`Blocked`	Open issues with unresolved blocking relations, ordered by priority.
`Changes`	Top-level issues only, grouped by status.

Avoid manually curated views. Filters must determine membership so the views stay correct when the CLI changes issue properties.

GitHub integration

The Linear GitHub integration is enabled. Use it for PR, commit, branch, check, and review visibility, but keep automatic Linear status transitions disabled. The Anuva CLI is the sole status writer because it applies repository, docs, dependency, verification, and completion-report preconditions that GitHub events alone cannot establish.

Branch names and PR titles or descriptions include the Linear issue ID so the integration links delivery automatically. The CLI verifies the exact issue/PR pair before submission, merge, and completion. Do not enable GitHub Issues sync; Linear remains the only issue system for Anuva work.

Documentation links

Every parent and implementation issue must link back to its durable documentation. Keep these link types distinct:

Link	When to set	Purpose
Product Main source path	At planning	Stable repository-relative location used by automation.
Review preview URL	During planning and implementation	Current working-tree page on the machine-specific gated MkDocs site.
Canonical docs URL	After successful manual publication	Reviewed aggregate page at `anuva.girishd.com`.
GitHub PR URL	When the PR is created	Code-delivery state and checks.

The issue description contains one CLI-managed link block with a deterministic marker. The CLI updates that block idempotently instead of appending duplicate comments or links.

Do not present a preview URL as canonical. After a successful anuva docs publish --push --confirm, verify the published page, derive its canonical URL from the publisher repository mapping, and synchronize that URL to the parent and affected implementation issues. Canonical publication and link synchronization remain an explicit user-approved operation.

Automation ownership

Concern	Owner
Intake content and priority	Linear parent issue
Product reasoning and approval record	Product Main Markdown
Child/standalone creation and state transitions	Anuva CLI
Blocking and parent/child relations	Linear through named CLI operations
PR linking and delivery visibility	Enabled Linear GitHub integration
Branch, PR, checks, review, and merge	GitHub
Preview and canonical link calculation	Anuva CLI documentation operations
Canonical publication	Explicit manual publish workflow

Avoid webhooks or additional background synchronization until the interactive CLI workflow has completed a pilot change. Automate repeated bookkeeping at named command boundaries rather than adding another workflow engine.

Initial configuration checklist

[ ] Confirm the single ANU team and six statuses with the documented Linear categories.
[ ] Disable parent/sub-issue auto-close.
[ ] Create the five repository labels and archive redundant workflow labels.
[ ] Create the default Change Intake template and optionally Quick Defect.
[ ] Create and favorite the five filtered views; make Next the default.
[ ] Verify the GitHub integration links branches and PRs.
[ ] Disable GitHub-driven Linear status transitions and GitHub Issues sync.
[ ] Update the Anuva CLI configuration and tests to the six-state model.
[ ] Pilot one parent change and at least one implementation child end to end.
[ ] Reassess labels, Projects, and Cycles only from pilot evidence.