> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weventures.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD & Project Tracking

> Automate deployments and track progress with Linear and Notion

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

## 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

<Steps>
  <Step title="Create /brief Directory">
    Create a `/brief` directory in your project root containing all planning documents:

    ```bash theme={null}
    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
  </Step>

  <Step title="Initialize Git Repository">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Connect to Linear">
    Your `/brief` directory should be synced with Linear for task tracking.

    **Linear Workspace:** [https://linear.app/workally/projects/all](https://linear.app/workally/projects/all)

    Initial setup creates a Linear project with tasks from `plan.md`.
  </Step>
</Steps>

***

## Linear MCP Integration

<Tabs>
  <Tab title="Setup Linear MCP">
    ### 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](https://linear.app/workally)
    * Linear API key
    * Claude Code installed

    ### Installation Steps

    <Steps>
      <Step title="Get Linear API Key">
        1. Go to [https://linear.app/workally/settings/api](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_`)
      </Step>

      <Step title="Configure MCP in Claude Code">
        Add Linear MCP to your Claude Code configuration:

        **Location:** `~/.claude/config.toml`

        ```toml theme={null}
        [mcp_servers.linear]
        command = "npx"
        args = ["-y", "@modelcontextprotocol/server-linear"]
        env = { LINEAR_API_KEY = "lin_api_your_key_here" }
        ```
      </Step>

      <Step title="Restart Claude Code">
        Restart Claude Code to load the Linear MCP server:

        ```bash theme={null}
        # If using CLI
        claude --reload-mcp

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

      <Step title="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.
      </Step>
    </Steps>

    ### 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.)
  </Tab>

  <Tab title="Update Workflow">
    ### 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:**

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

    Make executable:

    ```bash theme={null}
    chmod +x .git/hooks/post-commit
    ```
  </Tab>

  <Tab title="Pull Request Sync">
    ### GitHub ↔ Linear Integration

    **All PRs and issues should sync to Linear automatically.**

    ### PR Creation Workflow

    When creating a pull request, update Linear:

    ```bash theme={null}
    # 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:**

    1. Go to [https://linear.app/workally/settings/integrations/github](https://linear.app/workally/settings/integrations/github)
    2. Connect your GitHub organization
    3. Enable bidirectional sync
    4. 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."
    ```
  </Tab>
</Tabs>

***

## Notion MCP Integration

<Tabs>
  <Tab title="Setup Notion MCP">
    ### 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/](https://www.notion.so/workally/)

    ### Installation Steps

    <Steps>
      <Step title="Get Notion Integration Token">
        1. Go to [https://www.notion.so/my-integrations](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**
      </Step>

      <Step title="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
      </Step>

      <Step title="Configure MCP in Claude Code">
        Add Notion MCP to `~/.claude/config.toml`:

        ```toml theme={null}
        [mcp_servers.notion]
        command = "npx"
        args = ["-y", "@modelcontextprotocol/server-notion"]
        env = { NOTION_API_KEY = "secret_your_token_here" }
        ```
      </Step>

      <Step title="Verify Connection">
        ```
        "Check Notion MCP connection and list my Notion databases"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Update Workflow">
    ### 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"
    ```
  </Tab>
</Tabs>

***

## Periodic Update Workflow

<CardGroup cols={2}>
  <Card title="Daily Updates" icon="calendar-day">
    **What to update:** Linear only

    **Frequency:** End of each day or after major task completion

    **Command:**

    ```
    "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
  </Card>

  <Card title="Milestone Updates" icon="flag-checkered">
    **What to update:** Linear + Notion

    **Frequency:** When completing major phases

    **Command:**

    ```
    "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
  </Card>
</CardGroup>

***

## GitHub Integration

### Connecting Issues & PRs to Linear

**Commit message format:**

```bash theme={null}
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

```bash theme={null}
# 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

<Steps>
  <Step title="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
  </Step>

  <Step title="Development">
    Work on feature, commit regularly:

    ```bash theme={null}
    git add .
    git commit -m "feat: Implement login form

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

    Relates to WOR-123"
    ```
  </Step>

  <Step title="Complete Task">
    ```
    "I finished implementing login. Update Linear WOR-123 to 'Done' and add completion summary."
    ```
  </Step>

  <Step title="Create PR">
    ```bash theme={null}
    gh pr create --title "feat: User authentication" --body "Fixes WOR-123"
    ```

    Then:

    ```
    "Update Linear WOR-123 with PR link and move to 'In Review'."
    ```
  </Step>

  <Step title="End of Day">
    ```
    "Review today's work and update Linear with progress on all active issues."
    ```
  </Step>

  <Step title="Phase Complete">
    ```
    "Phase 1 complete! Update Linear milestone, create Notion documentation page, and prepare for Phase 2."
    ```
  </Step>
</Steps>

***

## Automation Best Practices

<CardGroup cols={3}>
  <Card title="Linear Updates" icon="list-check">
    **Frequency:** Daily or per-task

    * Mark tasks done immediately
    * Add blockers as comments
    * Update time estimates
    * Link PRs and commits
  </Card>

  <Card title="GitHub Sync" icon="code-branch">
    **Frequency:** Every PR

    * Use Linear issue IDs in commits
    * Link PRs to issues
    * Auto-close issues on merge
    * Tag releases properly
  </Card>

  <Card title="Notion Docs" icon="book">
    **Frequency:** Major milestones only

    * Phase completions
    * MVP launch
    * Production releases
    * Quarterly reviews
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Linear MCP Not Connecting">
    **Check API key:**

    ```bash theme={null}
    # 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"
    ```
  </Accordion>

  <Accordion title="Notion MCP Not Working">
    **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"
    ```
  </Accordion>

  <Accordion title="GitHub Issues Not Syncing">
    **Setup Linear GitHub integration:**

    1. [https://linear.app/workally/settings/integrations/github](https://linear.app/workally/settings/integrations/github)
    2. Connect organization
    3. Enable bidirectional sync
    4. Use `Fixes WOR-###` in commits
  </Accordion>
</AccordionGroup>

***

<Card title="Next Step" icon="arrow-right" href="/ai-development/prompting/frontend">
  With CI/CD and tracking configured, proceed to frontend implementation patterns →
</Card>