CI/CD & Project Tracking

This workflow integrates your development process with Linear for task tracking and Notion for milestone documentation.

Overview

After completing the planning and prompting phases, establish a robust CI/CD pipeline and project tracking system to maintain visibility and automate deployments.

Project Structure Setup

Create /brief Directory

Create a /brief directory in your project root containing all planning documents:

mkdir brief
cd brief

Required files:

claude.md - Project configuration and tech stack
plan.md - Phased implementation roadmap
discovery.md - User research and requirements (if applicable)
design-system.md - Brand guidelines and UI specifications

Initialize Git Repository

git init
git add .
git commit -m "Initial commit: Project brief and planning docs"
git branch -M main
git remote add origin https://github.com/Weventures-AI/your-project.git
git push -u origin main

Connect to Linear

Your /brief directory should be synced with Linear for task tracking.Linear Workspace: https://linear.app/workally/projects/allInitial setup creates a Linear project with tasks from plan.md.

Linear MCP Integration

Setup Linear MCP
Update Workflow
Pull Request Sync

Configure Linear MCP for Claude Code

Linear MCP enables Claude Code to automatically create and update tasks in Linear based on your plan.md.Prerequisites:

Linear account at https://linear.app/workally
Linear API key
Claude Code installed

Installation Steps

Get Linear API Key

Go to https://linear.app/workally/settings/api
Click “Create new key”
Name it “Claude Code MCP”
Copy the API key (starts with lin_api_)

Configure MCP in Claude Code

Add Linear MCP to your Claude Code configuration:Location: ~/.claude/config.toml

[mcp_servers.linear]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-linear"]
env = { LINEAR_API_KEY = "lin_api_your_key_here" }

Restart Claude Code

Restart Claude Code to load the Linear MCP server:

# If using CLI
claude --reload-mcp

# If using VS Code extension
# Reload VS Code window (Cmd+Shift+P -> Reload Window)

Verify Connection

Ask Claude Code to test the connection:

"Check if Linear MCP is connected and list my Linear projects"

Claude should respond with your Linear projects.

Initial Project Setup

Once configured, create your Linear project from plan.md:

"Read brief/plan.md and create a new Linear project called '[Project Name]' with all phases as milestones and tasks as issues. Tag them appropriately with phase numbers."

Claude Code will:

Create a Linear project
Create milestones for each phase
Create issues for each task
Link issues to milestones
Add labels (phase-0, phase-1, etc.)

Updating Linear Throughout Development

Update Frequency:

After each completed task - Mark issue as done
After major milestones - Update milestone progress
Daily standup - Sync current progress

Update Commands

Mark task complete:

"I just finished implementing user authentication. Update the corresponding Linear issue to 'Done' and add a comment with what was completed."

Update milestone progress:

"Phase 1 is now complete. Update all Phase 1 issues in Linear to 'Done' and update the milestone."

Daily progress sync:

"Review plan.md and update Linear with current progress. Mark completed tasks as done and update issue descriptions with any blockers or notes."

Create new issues for bugs:

"Found a bug with login form validation. Create a Linear issue in the [Project Name] project with priority High and label 'bug'."

Automated Updates

Configure Claude Code to automatically update Linear on git commits:Git hook setup:

# .git/hooks/post-commit
#!/bin/bash
claude "Update Linear with the changes from this commit: $(git log -1 --pretty=%B)"

Make executable:

chmod +x .git/hooks/post-commit

GitHub ↔ Linear Integration

All PRs and issues should sync to Linear automatically.

PR Creation Workflow

When creating a pull request, update Linear:

# After creating PR
gh pr create --title "Add user authentication" --body "Implements login/signup flows"

Then update Linear:

"I just created PR #23 for user authentication. Update the corresponding Linear issue with the PR link and move it to 'In Review'."

Automatic PR ↔ Linear Sync

Using Linear’s GitHub integration:

Go to https://linear.app/workally/settings/integrations/github
Connect your GitHub organization
Enable bidirectional sync
Configure PR → Issue linking

Result:

PRs automatically link to Linear issues via commit messages
Use format: Fixes WOR-123 in commit messages
Linear issues auto-update when PR is merged

Manual PR Updates

"PR #23 was merged. Update Linear issue WOR-45 to 'Done' and add deployment info."

Notion MCP Integration

Setup Notion MCP
Update Workflow

Configure Notion for Milestone Documentation

Notion is used for major milestone documentation only, not day-to-day tracking.Notion Workspace: https://www.notion.so/workally/

Installation Steps

Get Notion Integration Token

Go to https://www.notion.so/my-integrations
Click ”+ New integration”
Name it “Claude Code MCP”
Select workspace: “WorkAlly”
Copy the Internal Integration Token

Share Database with Integration

Open your Notion project database
Click “Share” → “Invite”
Search for “Claude Code MCP”
Grant Edit access
Copy the database ID from URL

Configure MCP in Claude Code

Add Notion MCP to ~/.claude/config.toml:

[mcp_servers.notion]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-notion"]
env = { NOTION_API_KEY = "secret_your_token_here" }

Verify Connection

"Check Notion MCP connection and list my Notion databases"

When to Update Notion

Update only on major milestones:

✅ Phase completion (Phase 0, Phase 1, etc.)
✅ MVP launch
✅ Major feature releases
✅ Production deployment
❌ NOT for every task or daily updates

Milestone Update Template

"Phase 1 is complete. Create a Notion page in the [Project Name] database with:
- Title: 'Phase 1: Authentication Complete - [Date]'
- Summary of completed features
- Screenshots/demos
- Deployment URL
- Metrics (if applicable)
- Next steps (Phase 2 preview)"

Example Update Commands

Phase completion:

"We just completed Phase 2 (Core Features). Update Notion with:
- Features implemented
- Performance metrics
- User feedback summary
- Link to staging deployment
- Screenshots"

Production launch:

"App is live in production! Create a comprehensive Notion launch report including:
- Launch date and time
- Production URL
- Launch checklist status
- Initial metrics
- Known issues
- Post-launch plan"

Periodic Update Workflow

Daily Updates

What to update: Linear onlyFrequency: End of each day or after major task completionCommand:

"Review today's progress in plan.md and update Linear. Mark completed tasks as done and add notes to in-progress issues."

Updates:

Mark completed Linear issues as Done
Update issue descriptions with progress
Create new issues for blockers
Update time estimates

Milestone Updates

What to update: Linear + NotionFrequency: When completing major phasesCommand:

"Phase [X] is complete. Update Linear to mark all Phase [X] issues as done, close the milestone, and create a comprehensive Notion page documenting this phase completion."

Updates:

Linear: Close milestone, mark all issues done
Notion: Create milestone documentation page
GitHub: Create release tag

GitHub Integration

Connecting Issues & PRs to Linear

Commit message format:

git commit -m "feat: Add user login

Implements email/password authentication with session management.

Fixes WOR-123"

Linear will automatically:

Link commit to issue WOR-123
Update issue status
Add commit link to issue timeline

Branch Naming Convention

# Format: type/WOR-###/description
git checkout -b feat/WOR-123/user-authentication
git checkout -b fix/WOR-456/login-validation
git checkout -b docs/WOR-789/api-documentation

Benefits:

Automatic issue linking
Clear PR organization
Easy filtering in GitHub

Complete Workflow Example

Start New Feature

"I'm starting work on user authentication (WOR-123). Create a feature branch and update Linear issue to 'In Progress'."

Claude Code will:

Create branch: feat/WOR-123/user-authentication
Update Linear issue status
Add start timestamp

Development

Work on feature, commit regularly:

git add .
git commit -m "feat: Implement login form

- Add email/password fields
- Add form validation
- Add loading states

Relates to WOR-123"

Complete Task

"I finished implementing login. Update Linear WOR-123 to 'Done' and add completion summary."

Create PR

gh pr create --title "feat: User authentication" --body "Fixes WOR-123"

Then:

"Update Linear WOR-123 with PR link and move to 'In Review'."

End of Day

"Review today's work and update Linear with progress on all active issues."

Phase Complete

"Phase 1 complete! Update Linear milestone, create Notion documentation page, and prepare for Phase 2."

Automation Best Practices

Linear Updates

Frequency: Daily or per-task

Mark tasks done immediately
Add blockers as comments
Update time estimates
Link PRs and commits

GitHub Sync

Frequency: Every PR

Use Linear issue IDs in commits
Link PRs to issues
Auto-close issues on merge
Tag releases properly

Notion Docs

Frequency: Major milestones only

Phase completions
MVP launch
Production releases
Quarterly reviews

Troubleshooting

Linear MCP Not Connecting

Check API key:

# View current config
cat ~/.claude/config.toml | grep LINEAR

# Test API key
curl -H "Authorization: lin_api_your_key" https://api.linear.app/graphql

Reload MCP:

"Reload MCP servers and verify Linear connection"

Notion MCP Not Working

Verify integration access:

Check integration has access to database
Verify database ID is correct
Ensure token is valid

Test connection:

"List all Notion databases I have access to"

GitHub Issues Not Syncing

Setup Linear GitHub integration:

https://linear.app/workally/settings/integrations/github
Connect organization
Enable bidirectional sync
Use Fixes WOR-### in commits

Next Step

With CI/CD and tracking configured, proceed to frontend implementation patterns →

AI Workflows

Prompting Guide

Model Training

Overview

Project Structure Setup

Linear MCP Integration

Configure Linear MCP for Claude Code

Installation Steps

Initial Project Setup

Updating Linear Throughout Development

Update Commands

Automated Updates

GitHub ↔ Linear Integration

PR Creation Workflow

Automatic PR ↔ Linear Sync

Manual PR Updates

Notion MCP Integration

Configure Notion for Milestone Documentation

Installation Steps

When to Update Notion

Milestone Update Template

Example Update Commands

Periodic Update Workflow

Daily Updates

Milestone Updates

GitHub Integration

Connecting Issues & PRs to Linear

Branch Naming Convention

Complete Workflow Example

Automation Best Practices

Linear Updates

GitHub Sync

Notion Docs

Troubleshooting

Next Step

AI Workflows

Prompting Guide

Model Training

Documentation Index

​Overview

​Project Structure Setup

​Linear MCP Integration

​Configure Linear MCP for Claude Code

​Installation Steps

​Initial Project Setup

​Updating Linear Throughout Development

​Update Commands

​Automated Updates

​GitHub ↔ Linear Integration

​PR Creation Workflow

​Automatic PR ↔ Linear Sync

​Manual PR Updates

​Notion MCP Integration

​Configure Notion for Milestone Documentation

​Installation Steps

​When to Update Notion

​Milestone Update Template

​Example Update Commands

​Periodic Update Workflow

Daily Updates

Milestone Updates

​GitHub Integration

​Connecting Issues & PRs to Linear

​Branch Naming Convention

​Complete Workflow Example

​Automation Best Practices

Linear Updates

GitHub Sync

Notion Docs

​Troubleshooting

Next Step

Overview

Project Structure Setup

Linear MCP Integration

Configure Linear MCP for Claude Code

Installation Steps

Initial Project Setup

Updating Linear Throughout Development

Update Commands

Automated Updates

GitHub ↔ Linear Integration

PR Creation Workflow

Automatic PR ↔ Linear Sync

Manual PR Updates

Notion MCP Integration

Configure Notion for Milestone Documentation

Installation Steps

When to Update Notion

Milestone Update Template

Example Update Commands

Periodic Update Workflow

GitHub Integration

Connecting Issues & PRs to Linear

Branch Naming Convention

Complete Workflow Example

Automation Best Practices

Troubleshooting