Skip to main content
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

1

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
2

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
3

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:

​
Installation Steps

1

Get Linear API Key

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

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" }
3

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)
4

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.)

​
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

1

Get Notion Integration Token

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

Share Database with Integration

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

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" }
4

Verify Connection

"Check Notion MCP connection and list my Notion databases"

​
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

1

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
2

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"
3

Complete Task

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

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'."
5

End of Day

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

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

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"
Verify integration access:
  1. Check integration has access to database
  2. Verify database ID is correct
  3. Ensure token is valid
Test connection:
"List all Notion databases I have access to"
Setup Linear GitHub integration:
  1. https://linear.app/workally/settings/integrations/github
  2. Connect organization
  3. Enable bidirectional sync
  4. Use Fixes WOR-### in commits

Next Step

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