shopify-linear-workflow

Shopify App — Linear Project Setup & Real-Time Workflow

This skill covers two phases that work together. Phase 1 runs once at the start of every new app. Phase 2 runs continuously throughout the entire build.

---

Phase 1: New App Project Setup

Run this phase exactly once, before any code is written.

Step 1 — Gather App Details

Ask the user to confirm (or infer from context):

Field	Example
App name	RewardFlow - Loyalty App
App purpose	One sentence — what problem it solves
Key features	4–8 main capabilities
App category	Marketing / Orders / Store design / etc.
Custom Prisma models needed	e.g. LoyaltyProgram, PointTransaction
Shopify API scopes needed	e.g. read_orders, write_customers

Use this info to tailor issue descriptions in Steps 4–5. Generic descriptions are less useful than ones that name the actual models and routes.

Step 2 — Create the Linear Project

Tool: save_project
name: [App name]          e.g. "RewardFlow - Loyalty App"
addTeams: ["GroPulse"]
icon: :rocket:

Note the returned project id — you'll need it when creating milestones.

Step 3 — Create 4 Milestones (in parallel)

Create all four in a single message using four simultaneous save_milestone calls:

Name	Description
1 — Setup	Boilerplate copy, TOML config, pricing tiers, Prisma schema, and project scaffolding.
2 — Core Features	All backend models, services, admin routes, theme extension, and storefront proxy.
3 — QA & Testing	E2E test scripts, security audit, and performance audit. All checks must pass before submission.
4 — Launch	App Store listing copy, icon, feature media, screenshots, and final submission.

Pass project: "[App name]" on every milestone call.

Step 4 — Create Phase Parent Issues

These are epics — one per phase. Child issues nest under them.

Create in parallel across all milestones:

Milestone: 1 — Setup

• Phase 1 — Research & Planning (priority: Urgent) — competitor analysis, feature spec, Linear issue creation
• Phase 2 — Boilerplate Scaffold & Project Setup (priority: Urgent) — copy boilerplate, update identifiers, configure scopes Milestone: 2 — Core Features
• Phase 3 — Database Schema & Backend (priority: Urgent) — Prisma schema, models, services, proxy, webhooks
• Phase 4 — Admin Frontend (priority: High) — all admin UI pages
• Phase 5 — Storefront Theme Extension (priority: High) — client-side JS, liquid blocks
• Phase 6 — Billing & Plan Gates (priority: High) — Shopify billing wiring, plan enforcement Milestone: 3 — QA & Testing
• Phase 7 — QA, Security Audit & Launch Prep (priority: Medium) — E2E tests, security/perf audits Milestone: 4 — Launch
• No parent issue needed here — Launch child issues are self-contained. For each parent issue, include a brief description listing what's in scope. Assign milestone and project on every call.

Step 5 — Create Child Issues

Create child issues under each parent. Tailor descriptions using the app details from Step 1 — name the actual models, routes, and features rather than using placeholders.

Under Phase 2 — Boilerplate Scaffold

• Copy boilerplate and scaffold [appname] app folder
• Update package.json, shopify.app.toml & scopes (list the actual scopes)
• Configure pricing tiers in app/config/pricing.ts
• Write Prisma schema — all [AppName] models (list the actual model names)

Under Phase 3 — Database Schema & Backend

• Build [entity].server.ts model files (one issue per major model group)
• Build visitor/session assignment service
• Build [core domain] service (e.g. loyalty.server.ts, rewards.server.ts)
• Build app proxy storefront API routes
• Build webhook handlers (orders/paid, app/uninstalled)

Under Phase 4 — Admin Frontend

• Update navigation in app.tsx
• Build Dashboard page (app._index.tsx)
• Build [primary entity] List page
• Build [primary entity] Create wizard
• Build [primary entity] Detail page
• Build Analytics page (app.analytics.tsx)
• Build Settings page (app.settings.tsx)
• Build Help page (app.help.tsx)

Under Phase 5 — Storefront Theme Extension

• Scaffold theme extension & [appname]-ab.js (or equivalent asset)
• Build liftoff-render.js equivalent (DOM manipulation)
• Build liftoff-track.js equivalent (conversion tracking)

Under Phase 6 — Billing & Plan Gates

• Add requirePlan / meetsMinimumPlan helpers to app/services/plan.server.ts
• Wire Shopify billing using billing.request() pattern

Under Phase 7 — QA & Testing

• E2E test — [primary user flow] full flow (e.g. price test, loyalty enrolment)
• E2E test — [secondary user flow] full flow
• Security audit — shopId scoping & HMAC verification
• Performance audit — theme extension bundle size & API latency

Under 4 — Launch (no parent, assign milestone directly)

• Write Shopify App Store listing content
• Generate app icon (AI image prompt + review output)
• Create feature media image (1600×900)
• Create screenshots — 5 minimum For every child issue: set parentId, milestone, project, and priority. Create child issues in parallel within each group, but wait for parent issues to be created first so you have their IDs.

Step 6 — Confirm and Start

Once everything is created:

1. Tell the user the Linear project is ready and share the project URL
2. Immediately mark the first child issue ("Copy boilerplate...") as In Progress
3. Begin the build

---

Phase 2: Real-Time Issue Tracking (Active Throughout the Build)

This is the most important change from the old approach. Follow these rules in every session.

The Core Rule

Mark an issue In Progress before writing the first line of code for it.
Mark it Done the moment that piece of work is complete.
Never batch — always update immediately.

The reason this matters: if a session ends unexpectedly, Linear reflects exactly where things stand. The next session can resume from the right place without re-reading the whole codebase.

Starting a task

1. Call save_issue with state: "In Progress" on the matching issue
2. Begin the work

Completing a task

1. Call save_issue with state: "Done"
2. Update the issue description with a brief summary: file paths created, key decisions, anything non-obvious
3. Immediately find the next issue and mark it In Progress

Starting a new session (resuming an existing app)

1. Call list_issues filtered to the project to see current state
2. Find the last In Progress or most recently completed Done issue
3. Determine what's next — mark it In Progress before starting
4. Never start coding without first updating Linear

Issue description on Done

When marking Done, update the description with:

• Files created / modified
• Key implementation decisions
• Any known limitations or follow-up items This creates a permanent readable history in Linear, which is especially useful when work resumes in a new session with a fresh context window.

---

Linear MCP Tool Reference

All calls use the mcp__2fe173a9-52f9-4062-bd39-ab36a2c936ca__* prefix:

Task	Tool
Create/update project	save_project
Create/update milestone	save_milestone
Create/update issue	save_issue
List issues	list_issues
List milestones	list_milestones
Get issue detail	get_issue

Always use team: "GroPulse" or project: "[App name]" on every call — never leave these unset.

---

Setup Checklist

Project setup is complete when all of these are true:

• Linear project created and visible in the GRO sidebar
• 4 milestones created with correct names
• Phase parent issues created and assigned to correct milestones
• Child issues created, assigned to parents + milestones
• First issue marked In Progress before any code is written
• User can open the project board in Linear and see the full work breakdown