ai-todo / rules

---
description: "Linear integration: kickoff, branching, ai-todo planning, closing"
alwaysApply: true
---

# Linear + ai-todo Integration Protocol

Your workflow connects high-level strategy (Linear) with low-level execution (ai-todo).

**Design:** See `docs/linear_integration_design.md` for full specification.

---

## THE GOLDEN RULE

**Never** write code without a plan in `TODO.md`.
**Never** start work without an assigned Linear Issue.

---

## TOOLCHAIN

- **Macro (Strategy):** Linear MCP (`user-linear`) — read requirements, update stakeholders.
- **Micro (Tactics):** ai-todo MCP — track execution steps.

---

## KICKOFF WORKFLOW

**Trigger:** When the user says **"Start work"**, **"Pick task"**, or **"Kickoff"**:

### Step 1: List issues

Call **user-linear.list_issues** with `{ "assignee": "me" }`.

### Step 2: Present

List the returned issues (identifier, title, status) and ask which one to work on.

### Step 3: Get issue

Once the user selects an issue (e.g., AIT-12):
- Call **user-linear.get_issue** with that issue's `id` (UUID) to get full details including `title`, `description`.
- **CRITICAL:** Linear returns a `gitBranchName` field - **IGNORE IT**. It uses Linear's `displayName` (e.g., "oliver"), not the GitHub username (e.g., "fxstein").

### Step 4: Branch

**CRITICAL: Always start from updated main. Always construct branch name from git config. NEVER use Linear's gitBranchName.**

**Pre-branch checks:**
1. Switch to main: `git checkout main`
2. Update from origin: `git pull origin main`
3. Verify clean state: `git status` (warn if uncommitted changes exist)

**Create branch:**
4. Get GitHub username: `git config user.name` (use as-is, case-sensitive)
5. Extract IDENTIFIER from Linear issue (e.g., `AIT-12`, keep case from Linear)
6. Create slug from issue title: lowercase with hyphens (e.g., `fix-login`)
7. Run: `git checkout -b <username>/<IDENTIFIER>-<slug>`

**Example:** If `git config user.name` returns "fxstein" and issue is AIT-12 "Fix Login":
```bash
git checkout main
git pull origin main
git checkout -b fxstein/AIT-12-fix-login
```

### Step 5: ai-todo Planning

After creating the branch:

- **Offer:** Ask: "Should I create an ai-todo task for this Linear issue?"
- **If yes:**
  1. Call **ai-todo.add_task** with:
     - `title`: `[<IDENTIFIER>] <issue title>` (e.g., `[AIT-12] Fix login validation`)
     - `description`: The Linear issue description (or summary).
  2. **If the Linear issue has subtasks or steps in the description:** Create subtasks with **ai-todo.add_subtask** for each step.
  3. **Confirm plan with user:** Show the created task/subtasks and ask "Does this plan look correct?"

### Step 6: Set state to In Progress

After branching (and optionally creating ai-todo tasks):

- **Offer:** Ask: "Should I set this Linear issue to **In Progress**?"
- **If yes:** Call **user-linear.update_issue** with:
  - `id`: Issue UUID (from step 3).
  - `state: "In Progress"`.

---

## CLOSING WORKFLOW

### Open Pull Request

**Trigger:** User says **"Open PR"**, **"Ready for review"**, or **"Create PR"**:

**Actions:**
1. Push branch: `git push -u origin HEAD`
2. Create PR with:
   - Title: `[IDENTIFIER] Issue title`
   - Body format:
     ```
     Closes [IDENTIFIER](linear-issue-url)

     ## Summary
     [Brief description from Linear issue or ai-todo task]

     ## Changes
     - [Key changes from commit messages]

     ## Test Plan
     - [How to verify - optional]
     ```
3. Set Linear to **In Review**: Call **user-linear.update_issue** with `id` and `state: "In Review"`

### After PR Merged

**Trigger:** User says **"PR merged"**, **"Close issue"**, or **"Done"**:

**Actions:**
1. Set Linear to **Done**: Call **user-linear.update_issue** with `id` and `state: "Done"`
2. Cleanup branch:
   - Switch to main: `git checkout main`
   - Update from upstream: `git pull origin main`
   - Delete local branch: `git branch -d <branch-name>`
   - Delete remote branch: `git push origin --delete <branch-name>`

---

## CRITICAL REMINDERS

- **API tools (user-linear):**
  - ✅ Use **user-linear.get_user** with `{ "query": "me" }` (not `get_viewer`).
  - ✅ Use **user-linear.list_issues** with `{ "assignee": "me" }` (not `get_issues` with `assignee_id`).
  - ✅ Use **user-linear.update_issue** with `state` parameter (not `status`).

- **Branch creation:**
  - **ALWAYS start from updated main:** `git checkout main && git pull origin main`
  - **NEVER create branches from stale or feature branches** (causes merge conflicts).
  - **NEVER use Linear's `gitBranchName` field** (it uses displayName, not GitHub username).
  - **ALWAYS** construct: `<username>/<IDENTIFIER>-<slug>`
  - Get username from: `git config user.name` (use as-is, case-sensitive).
  - Example: `fxstein/AIT-12-fix-login` (NOT `oliver/AIT-12-fix-login`)
  - GitHub PR check accepts case-insensitive identifier (AIT or ait).

- **ai-todo planning:**
  - Always offer to create ai-todo tasks from Linear issues.
  - Use format `[IDENTIFIER] Title` for the main task.
  - Create subtasks if the Linear issue has steps.

---

*This rule combines kickoff, branching, ai-todo planning, and closing workflows. For full context: `docs/linear_integration_design.md`, `docs/linear_integration_assessment.md`.*