Projects

A Project in GuideMode represents a body of work that spans issues across one or more repositories. Projects can be imported from GitHub Projects, Linear Projects, Jira Projects, or created manually. They provide a higher-level view of work than individual issues.

Overview

Projects in GuideMode:

• Group related issues across repositories
• Track progress with timeline and completion metrics
• Span multiple providers for unified project views
• Link to teams for ownership and filtering
• Connect to repositories for code context

Project Structure

Key Fields

Field	Type	Description
name	string	Project display name
description	string	Project description (optional)
provider	enum	’github’, ‘linear’, ‘jira’, ‘notion’, ‘manual’
externalId	string	Provider’s project ID
url	string	Web URL to project in provider
status	enum	’active’, ‘completed’, ‘archived’
startDate	timestamp	Project start date
targetDate	timestamp	Target completion date
progressPercent	integer	Completion percentage (0-100)
syncEnabled	boolean	Whether to sync from provider

Project Status

Projects have a simple lifecycle:

Status	Description
active	Project is in progress, issues being worked
completed	Project finished, all work complete
archived	Project closed, no longer active

Provider Integration

GitHub Projects (v2)

Field	Description
githubProjectNumber	Project number within organization
githubOrgLogin	Organization login (e.g., “acme-corp”)
githubProjectId	GraphQL node ID

GitHub Projects v2 are synced from your connected organizations. They maintain their GitHub structure and items.

Linear Projects

Field	Description
linearProjectId	Linear project UUID
linearTeamId	Optional owning team ID

Linear projects include their team association and sync progress tracking.

Jira Projects

Field	Description
jiraProjectId	Jira project ID
jiraProjectKey	Project key (e.g., “PROJ”, “KAN”)
jiraCloudId	Jira cloud instance ID

Jira projects are identified by their key (the prefix on issue numbers like “PROJ-123”).

Manual Projects

Projects with provider: 'manual' are created directly in GuideMode. Use them to:

• Group issues from multiple providers
• Create ad-hoc project views
• Track work not represented in any tool

Project Relationships

Project-Issue Links

Issues can be linked to projects, creating a containment relationship:

Each link includes:

• position - Order within the project (for prioritization)
• addedAt - When the issue was added to the project

Project-Repository Links

Projects can be associated with repositories:

This enables:

• Filtering PRs/deployments by project
• Understanding which codebases a project touches
• Repository-level project metrics

Team-Project Assignments

Projects can be assigned to teams for ownership:

Projects can have multiple team owners for cross-functional work.

Timeline Tracking

Projects track timeline information for planning and progress:

Field	Description
startDate	When work should begin
targetDate	Expected completion date
progressPercent	Current completion (0-100)

Progress Calculation

Progress can be:

• Provider-synced - From GitHub/Linear/Jira progress fields
• Issue-based - Calculated from closed vs total issues
• Manual - Set directly in GuideMode

Sync Behavior

Projects with syncEnabled: true will:

1. Sync project metadata - Name, description, status, dates
2. Sync linked issues - Issues added/removed from project
3. Update progress - If provider supports it
4. Track timestamps - lastSyncedAt for freshness

Disabling Sync

Set syncEnabled: false to:

• Keep project in GuideMode but stop syncing
• Preserve manual modifications
• Reduce API calls for inactive projects

Use Cases

Cross-Provider Projects

A single GuideMode project can reference issues from multiple providers:

Project: "Q1 Platform Initiative"
├── GitHub Issue: "Migrate to new API"
├── Jira Issue: "Database schema update"
├── Linear Issue: "Performance benchmarks"
└── Notion Page: "Architecture decisions"

Sprint/Cycle Tracking

Use projects to track sprints or development cycles:

• Set startDate and targetDate to sprint boundaries
• Link all sprint issues
• Track progress through completion percentage

Initiative Tracking

For larger initiatives spanning multiple teams:

• Create a manual project
• Assign to multiple teams
• Link repositories and issues as needed
• Track overall progress

Related Documentation

Core Concepts

• Teams - Team ownership of projects
• Repositories - Project-repository relationships
• Issues - Project-issue relationships

Integrations

• Integrations Overview - Connect your project tools
• GitHub Integration - GitHub Projects sync
• Linear Integration - Linear Projects sync
• Jira Integration - Jira Projects sync