Instagantt to Linear Projects Migration Plan
1. Goal and reasons for migration
Goal: Use Linear Projects (with initiatives, projects, milestones, and issues) as the single source of truth for client timelines and progress, replacing Instagantt.
Reasons:
- No Instagantt API/MCP: Kickoffs and updates cannot be automated; today the client-engagement-kickoff generates an Instagantt CSV (Step 8) and relies on manual import and link-back. No programmatic read/write of Instagantt.
- Disconnected timelines: Instagantt workbooks hold phases/deliverables and dates; Linear holds issues. Progress is tracked in two places, so status and timeline are not visible in one view and EP audit / weekly kick-off cannot reason about project or milestone health.
- Single source of truth: Linear MCP already supports projects, milestones, and initiatives. Moving timelines into Linear enables one system for tasks, milestones, and roadmap and allows skills (kickoff, update, audit) to read and write the same data.
Out of scope for this plan: Changing how cycles or backlogs are used; that stays as-is unless a later iteration decides otherwise.
2. Hierarchy mapping (Instagantt / PM plan to Linear)
Your intended mapping is consistent with Linear’s model:
| Layer | Linear entity | Brainforge meaning | Example |
|---|---|---|---|
| Initiative | Initiative | General workstream | Data, Strategy, A.I |
| Sub-initiative | Initiative (with parentInitiative) | Client/service line | E2A – MinuteMD, MarTech – Eden |
| Project (Epic) | Project | Client epic | MinuteMD: Push Test to Production |
| Milestone | Milestone (on Project) | Client-impacting deliverable | MinuteMD: Start single-page test |
| Task | Issue | Individual work item | MinuteMD: Single Page Test |
Linear MCP supports: Initiatives (save_initiative, list_initiatives, get_initiative) with parentInitiative for sub-initiatives; Projects (save_project, list_projects, get_project) with startDate/targetDate, setInitiatives, and team(s); Milestones (save_milestone, list_milestones, get_milestone) on a project with targetDate; Issues (save_issue, list_issues, get_issue) with project, optional parentId for sub-tasks.
Visual deliverable: Use the visual-explainer skill to produce a diagram of this hierarchy (Initiatives → Sub-initiatives → Projects → Milestones → Issues) and, if useful, a second diagram showing migration flow (workbooks → teams → projects/milestones).
3. Initial migration plan
3.1 One-time migration
- Source: All current Instagantt workbooks (per client or per engagement). Assumption: Workbooks are known and accessible (e.g. we have a list per client, or migration runs on demand from an existing inventory). Workbook inventory owner: CSO per client (or Delivery lead) maintains the list of workbooks for their clients; Ops maintains a global inventory if one exists. Document or create that list in playbook or
knowledge/clients/{client}/resources/before migration. - Target: Existing Linear teams (one team per client, e.g. GLO, MMD, CTA). Create Linear Projects (and optionally Milestones) that mirror current Instagantt structure; do not create initiatives/sub-initiatives in this step unless the canonical mapping from §3.2 already exists.
- Who runs it / runbook: Migration is run by a human using a playbook runbook (checklist + Linear MCP in Cursor). Runbook location:
standards/03-knowledge/engineering/setup/instagantt-to-linear-migration-runbook.md(or equivalent under playbook). The runbook must include: (1) prerequisite workbook inventory per client, (2) step-by-step (export → map → create projects/milestones → link issues), (3) path or command so Ops can re-run or hand off (e.g. “Run in Cursor with playbook steps” or one-off script path if added later). Pilot validation: Delivery lead or CSO validates one or two pilot clients in Linear UI (check projects, milestones, and issue links); sign-off is “Migration log updated and team informed.” - Process:
- Export from Instagantt (manual CSV or screen/structure capture) per workbook.
- For each workbook: map workbook → Linear team; map top-level phases/groups → Linear Projects (create via
save_projectwithname,startDate,targetDate, team viasetTeams); map deliverables/phases with dates → Milestones on that project (save_milestonewithproject,name,targetDate). - Link existing Linear issues to the new projects where possible using
save_issuewithprojectset. Acceptance: Link when issue title or description matches a project/deliverable name, or when the issue is listed in a one-off mapping (e.g. CSV or playbook table); otherwise leave unlinked.
- Documentation: Add a short “Migration log” (e.g. in playbook or vault) listing workbooks migrated, Linear team, and project names/IDs so the Audit skill and future runs can assume this structure.
3.2 Mapping of “project management plan” to Linear
- Project management plan = the set of workstreams (Data, Strategy, A.I), client services (E2A–MinuteMD, MarTech–Eden, etc.), and epics/deliverables you track today in Instagantt or docs.
- Mapping: Document in playbook (or a single mapping doc) the canonical list: Initiative name → Sub-initiatives (client/service) → for each client team, the default or expected Project names (epics). The Kickoff skill will create Projects under the right team and optionally attach them to Initiatives; Update/Edit and Audit will use this mapping to find the right projects and milestones.
3.3 Rollback
- Instagantt remains read-only (no delete). Linear creates are additive; if you need to “roll back,” you can archive Linear projects or leave them and fix data in a second pass. No automated rollback required for the plan.
4. Three main Linear project skills
4.1 Kickoff (setup Linear Gantt/timeline from the start)
- Trigger: Same as today’s client engagement kickoff (e.g. “kick off new client”, “run client engagement kickoff”). After vault, Notion, SOW, Data Platform doc, and Linear issues from SOW (current Step 7), the skill additionally:
- Creates or reuses Initiatives/Sub-initiatives per the canonical mapping (e.g. workstream + client service).
- Creates Linear Projects (epics) from SOW phases/deliverables, with
startDate/targetDate(from SOW timeline or sprint start), and attaches them to the correct team and initiatives. - Creates Milestones on each project for client-impacting deliverables (from SOW), with
targetDate. - Links the issues already created from the SOW to the new projects. Issue–milestone linkage (decided): We do not link issues to milestones in Linear for this implementation; milestones are date markers for client-impacting deliverables. Kickoff and Audit use project + milestone
targetDateonly; issues are associated with projects. If Linear later supports issue–milestone linkage (e.g. custom field), we can revisit in a future iteration.
- Replacement: Step 8 (Instagantt CSV) is removed; instead, the kickoff writes directly to Linear via MCP. README and resources no longer mention Instagantt CSV; they point to Linear project/roadmap views.
- Comms: When Step 8 is removed, inform the internal team (CSOs, delivery) that kickoff no longer produces an Instagantt CSV and that timelines live in Linear. Optionally notify clients that roadmap/timeline views are in Linear (or leave client comms to CSO discretion).
- Reference: client-engagement-kickoff and playbook SOW parsing (phases, milestones, deliverables, timeline).
4.2 Update/Edit (update Linear project timelines and status)
- Location: New skill under
.cursor/skills/linear-project-update/(or equivalent); optionally also a Cursor command for quick trigger. Implementer creates the skill file and, if desired, a command that invokes it. - Trigger: E.g. “Update Linear project timeline for [client]”, “Set milestone dates for [project]”, “Refresh project status from SOW/transcript.”
- Behavior:
- Projects: Update
startDate,targetDate,state,description(e.g. from SOW change or internal decision). - Milestones: Create new milestones, update
targetDateor name/description viasave_milestone. - Issues: Optionally move issues between projects, update status/due dates so they align with milestone dates (using existing
save_issue).
- Projects: Update
- Inputs: Client/project name, and either explicit date/scope changes or a reference (SOW, transcript, Slack) from which to infer updates. Confirm before applying bulk changes.
4.3 Audit (are projects, milestones, and timelines up-to-date; are there risks?)
- Trigger: Embedded in existing workflows; not only a standalone “run project audit” command.
- Embedding:
- EP audit (Linear board audit): Extend linear-board-audit-sop.md (and subagent prompt) so that in addition to issues, the audit reads the client’s Linear projects and milestones (
list_projectsby team,list_milestonesper project,get_projectwithincludeMilestones). Output a short “Project/milestone health” subsection per client. Format template: Overdue: [project/milestone names with past targetDate]. At-risk: [milestones due soon or projects with no recent issue activity]. Risks: [e.g. many issues in backlog, key work unassigned]. No new tool—same Linear MCP; add one consolidated “project + milestone” read step. - Weekly kick-off update: Extend weekly-kick-off-update-sop.md so that when gathering Linear context it also fetches projects and milestones for the client team. Include in the draft (and optionally in the Slack block) a one-line “Timeline” or “Milestones” line (e.g. “Push Test to Production (target Apr 15); Single-page test start (Mar 22)” and any overdue/at-risk callouts).
- Data platform doc update / backfill: If the Data Platform Documentation or other skills reference “project status” or “timeline,” add an optional step: “If client has Linear projects/milestones, summarize current target dates and at-risk items” using the same read pattern (list_projects by team, list_milestones, then summarize). No requirement to change sheet schema; only enrich context where it helps.
- EP audit (Linear board audit): Extend linear-board-audit-sop.md (and subagent prompt) so that in addition to issues, the audit reads the client’s Linear projects and milestones (
- Standalone: Allow “Run project audit for [client]” or “Are our Linear projects up to date?” to run the same project/milestone health check and output the same subsection (overdue, at-risk, no activity) without running the full EP audit.
Visual deliverable: Use visual-explainer to produce a small workflow diagram: Kickoff → creates projects/milestones/issues; Update/Edit → updates dates and status; Audit → reads projects/milestones and embeds in EP audit, weekly kick-off, and optionally data-platform doc flow.
5. Linear MCP tool map (for skills; avoid scanning full tool list)
Curated list so each skill references only the tools it needs. Linear MCP server name (for call_mcp_tool): Use the actual server id from your Cursor MCP config (e.g. project-0-brainforge-platform-linear or user-linear); the plan assumes the same server hosts all tools below. The exact value is config-dependent—skills and the tool map doc should reference “Linear MCP server id from Cursor MCP config” rather than a hardcoded name.
Initiatives
| Tool | Use in skills | Purpose |
|---|---|---|
list_initiatives | Kickoff, Audit | List workstreams/sub-initiatives; filter by parentInitiative, status. |
get_initiative | Kickoff, Update, Audit | Get one initiative (e.g. by name) and its projects if needed. |
save_initiative | Kickoff, Update | Create or update initiative; set parentInitiative for sub-initiatives, status, targetDate. |
Projects
| Tool | Use in skills | Purpose |
|---|---|---|
list_projects | Kickoff, Update, Audit | List by team, initiative; use includeMilestones: true when you need milestones. |
get_project | Kickoff, Update, Audit | Get one project by name/ID/slug; includeMilestones, includeMembers, includeResources as needed. |
save_project | Kickoff, Update | Create or update project; set name, startDate, targetDate, state, setTeams, setInitiatives, description. |
Milestones
| Tool | Use in skills | Purpose |
|---|---|---|
list_milestones | Kickoff, Update, Audit | List milestones for a project (name/ID/slug). |
get_milestone | Update, Audit | Get one milestone (e.g. by name/ID). |
save_milestone | Kickoff, Update | Create or update milestone; require project; set name, targetDate, description. |
Issues
| Tool | Use in skills | Purpose |
|---|---|---|
list_issues | Kickoff, Audit, EP audit, Weekly kick-off | List by team, project, state, assignee, etc. |
get_issue | Update, Audit | Get one issue. |
save_issue | Kickoff, Update, EP audit | Create or update issue; set project, state, dueDate, etc. |
Teams and users
| Tool | Use in skills | Purpose |
|---|---|---|
list_teams | Kickoff, Audit | Resolve client → team. |
get_team | Kickoff | Team details if needed. |
list_users | Kickoff, Update | Resolve assignee by name/email. |
Optional (comments, status, docs)
| Tool | Use in skills | Purpose |
|---|---|---|
save_comment | Update, Audit | Add comment on issue (e.g. “Status from sync”). |
get_status_updates / save_status_update | Optional | If you use Linear status updates for projects. |
list_cycles | Audit | If you want to compare backlog vs current cycle. |
Not needed for the three skills: create_document, list_documents, create_attachment, extract_images, search_documentation, label create/delete, etc., unless a future iteration adds doc-heavy workflows.
Deliverable: Add a single “Linear MCP tool map” doc (e.g. in playbook or .cursor/skills/ as a shared reference) that lists the tools above by skill (Kickoff / Update / Audit) and purpose, so skill files can say “Use only tools from the Linear project tool map for Kickoff” and the agent does not need to scan the full MCP tool list.
6. Implementation order (suggested)
- Document the canonical Initiative / Sub-initiative / Project naming and team mapping in playbook (or vault).
- Add the Linear MCP tool map doc and reference it from skill stubs.
- One-time migration: Run the workbook → Linear project/milestone migration for one or two pilot clients; validate in Linear UI. Document where the migration is run (playbook runbook, Cursor command, or one-off script path) so Ops can re-run or hand off.
- Kickoff skill: Extend client-engagement-kickoff to create projects + milestones and link issues; remove Instagantt CSV step; update README/resources.
- Update/Edit skill: New skill or command; implement project/milestone (and optional issue) updates with confirmation.
- Audit: Extend EP audit and weekly kick-off SOPs with project/milestone reads and the “Project/milestone health” subsection; add standalone “project audit” trigger.
- Optional: Data platform doc update/backfill enrichment with project/milestone summary.
- Run document council on the plan doc and generate visuals; iterate once if needed.
7. Open decisions (to be resolved before or during implementation)
- Resolved: One-time migration is run by a human via playbook runbook (see §3.1 runbook location); re-run or handoff path documented there.
- Resolved: Issues are not linked to milestones; milestones are date markers; issues are linked to projects only (see §4.1).
- Resolved: Linear server id is read from Cursor MCP config; tool map and skills reference it generically (see §5).
- Still open: Naming convention for initiatives (e.g. “Data”, “Strategy”, “A.I”) and sub-initiatives (e.g. “E2A – MinuteMD”) so Kickoff can create or match them idempotently—document in canonical mapping (§3.2) before Kickoff implementation.
References
- Client engagement kickoff skill (Step 8 Instagantt CSV to be replaced).
- Linear board audit SOP and subagent prompt.
- Weekly kick-off update SOP.
- Document council personas.
- Visual explainer skill.
- Linear MCP tool descriptors (e.g.
save_project,save_milestone,save_initiative,list_,get_) under your Cursor MCP project folder for exact parameters.