> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Planning

> Canonical planning pack and the recommended Linear operating model for this repo.

# Linear Planning

This repository now has a dedicated planning pack for Linear under `planning/linear/`.

That pack is the intended execution bridge between:

* long-form source docs in `docs/`
* active project management in Linear
* issue-level implementation work
* substantial discoveries found during implementation

## Canonical files

* `planning/linear/README.md`
* `planning/linear/OPERATING_MODEL.md`
* `planning/linear/PROJECT_BRIEF.md`
* `planning/linear/BACKLOG.yaml`
* `planning/linear/ISSUE_TEMPLATES.md`

## Recommended structure in Linear

* one primary team for active execution
* initiatives for strategic streams
* projects for concrete outcomes
* milestones for checkpoints
* one `Overview` document per project
* issues for PR-sized slices

The current workspace uses an initiative/project portfolio rather than a redundant umbrella project.

## Why this exists

The repo had accumulated:

* a long-form PRD
* a numbered implementation sequence
* migration planning
* hardening backlog
* feature-flag strategy
* customization and builder review

Those documents are still valuable, but they should be source material, not parallel execution surfaces.

## Rule of thumb

If a planning artifact does not clearly map to:

* initiative
* project
* milestone
* issue
* project document

then it probably should not become a new planning document.

## Sync behavior

`pnpm linear:sync` and `pnpm linear:sync:apply` treat `planning/linear/*` as the source for:

* initiatives
* projects
* milestones
* one project `Overview` document per project
* seed issues

Seeded project updates are available, but they are explicit rather than automatic:

```bash theme={null}
pnpm linear:sync:apply:with-updates
```

Substantial blockers, parity gaps, and architectural gaps found during coding should not remain in chat logs or PR prose. They should become a created or updated Linear issue before the session closes.

## Read next

* [Roadmap](/roadmap)
* [Adversarial Review](/operations/adversarial-review)
* [Platform Architecture](/platform/architecture)