Learning

Linear Project Lifecycle

Linear Project Lifecycle for New Projects Proposal For new projects, use a two-layer operating model: Git docs are the source of truth for scope, requirements,

Source: learning/setup/linear-project-lifecycle.mdUpdated 2026-04-24

Linear Project Lifecycle for New Projects

Proposal

For new projects, use a two-layer operating model:

  • Git docs are the source of truth for scope, requirements, architecture, and decisions.
  • Linear is the execution and coordination layer for tasks, milestones, blockers, and approvals.

This keeps planning durable in Git while keeping delivery visible and actionable in Linear.

Example Project: Leave Management Web Application

A Leave Management web app is a good example because it has clear business rules, multiple user roles, and an end-to-end workflow that is easy to organize in stages.

---

1. New Project Creation

Trigger

A new business need or product idea is identified.

Example:

  • "We need a web application for employees to request leave and managers to approve it."

What to create

In Git

Create a project folder and the initial docs:

  • ~/workspace/projects/p02-leave-management/
  • project.yaml
  • docs/00-index.md
  • docs/01-vision.md
  • docs/02-scope.md
  • docs/03-requirements.md
  • docs/04-architecture.md
  • docs/05-data-model.md
  • docs/06-workflows.md
  • docs/07-mvp-plan.md
  • docs/08-release-notes.md
  • docs/09-open-questions.md

In Linear

Create a Linear project:

  • Leave Management

Then create a few seed issues for discovery and planning.

Output of this phase

  • A project exists in Git
  • A matching project exists in Linear
  • The initial open questions are visible
  • No implementation has started yet

---

2. Project Planning

This is the phase where the idea becomes a concrete delivery plan.

Git docs updated

Use the docs to define the project clearly:

  • 01-vision.md: why the project exists
  • 02-scope.md: what is in and out of scope
  • 03-requirements.md: functional and non-functional requirements
  • 04-architecture.md: system design and major components
  • 05-data-model.md: entities such as leave request, leave balance, approval records
  • 06-workflows.md: request, approve, reject, notify, audit
  • 07-mvp-plan.md: what will be built first

Linear updated

Create milestones or major issues such as:

  • Authentication and roles
  • Leave request submission
  • Manager approval flow
  • Leave balance tracking
  • Notifications
  • Audit log
  • Admin policy configuration

Approval gate

The plan should be reviewed before execution starts.

Possible decisions:

  • Approved as-is
  • Approved with changes
  • Not approved yet

If not approved:

  • update the docs
  • adjust scope or architecture
  • review again

Output of this phase

  • The project plan is clear
  • The MVP boundary is defined
  • The first execution backlog is ready

---

3. Project Execution

This is the implementation phase.

Suggested execution order for the Leave Management app

Phase A: Foundation

  • repository setup
  • environment setup
  • authentication
  • user roles: employee, manager, admin
  • database schema

Phase B: Core Leave Flow

  • employee submits leave request
  • manager sees pending requests
  • manager approves or rejects
  • leave balance updates
  • request status is recorded

Phase C: Supporting Capabilities

  • notifications
  • audit trail
  • admin policy management
  • reporting

How Linear is used

Each issue should be a concrete deliverable, for example:

  • Create leave_request table
  • Implement employee leave request form
  • Add manager approval action
  • Send approval notification
  • Add audit log entry

Track each issue through a shared workflow such as:

  • Backlog
  • Ready
  • In Progress
  • Blocked
  • Done

How Git docs are used during execution

If anything changes in a meaningful way, update the docs first or alongside the change:

  • requirement changes -> update 03-requirements.md
  • architecture changes -> update 04-architecture.md
  • workflow changes -> update 06-workflows.md
  • new questions -> add to 09-open-questions.md

Output of this phase

  • Features are implemented as tracked Linear issues
  • The docs stay aligned with the implementation
  • Blockers are visible

---

4. Review and Approval for Tasks

This is the quality gate during execution.

Task-level review

After a task is completed, review it for:

  • correctness
  • code quality
  • test coverage
  • alignment with the docs
  • security and permission behavior

Example: Task: Implement manager approval

A reviewer checks that:

  • only managers can approve
  • approved and rejected states are persisted correctly
  • audit logging occurs
  • the UI handles errors safely

Possible outcomes:

  • Approved
  • Changes requested
  • Rejected

If changes are requested:

  • create follow-up fixes as Linear issues
  • re-review after the fixes are made

Feature-level review

After a related group of tasks is complete, test the full end-to-end flow.

Example:

  1. employee submits a leave request
  2. manager approves it
  3. leave balance updates
  4. notification is sent
  5. the audit log records the action

This is important because individual tasks can pass while the full feature still fails as a system.

Output of this phase

  • Each task has a review decision
  • Feature behavior is validated end-to-end
  • Rework is tracked explicitly

---

5. Final Review

This happens when the MVP or release candidate is complete.

What to review

  • all MVP scope items
  • remaining open questions
  • known limitations
  • documentation completeness
  • operational readiness
  • release notes

Final review checklist for the Leave Management app

  • Can employees request leave?
  • Can managers approve or reject leave?
  • Are leave balances correct?
  • Is audit logging present?
  • Are notifications working?
  • Are permissions correct?
  • Are docs up to date?
  • Are release notes written?

Approval gate

If the final review passes:

  • mark the release complete
  • write release notes
  • freeze the baseline if needed
  • create next-phase backlog if applicable

If the final review fails:

  • create fix issues in Linear
  • update the docs
  • review again

Output of this phase

  • The project is ready for release
  • The release is documented
  • The next iteration path is clear

---

In Git

  • define the project
  • keep the design current
  • record decisions and open questions
  • preserve release notes and frozen baselines

In Linear

  • track actual work
  • manage priorities and blockers
  • assign owners
  • move tasks through execution and review

Suggested Linear project stages

  • Draft
  • Planned
  • In execution
  • In review
  • Ready to release
  • Released

---

7. Short Version of the Flow

  1. Create the project in Git and Linear
  2. Write the project plan in docs
  3. Approve the plan
  4. Break the plan into Linear issues
  5. Execute the tasks
  6. Review each task
  7. Review the integrated feature set
  8. Do the final release review
  9. Release and freeze the baseline if needed

---

8. Core Rule

Docs define intent. Linear defines action. Approval happens before moving to the next phase.

No task should enter execution without a clear requirement, and no project should be released without a final integrated review.