Skip to main content

​
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
  • 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:
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.