team-toon-tack 1.6.3 → 1.7.1

package/README.md

@@ -2,54 +2,68 @@
 
 [繁體中文](./README.zh-TW.md) | English
 
-CLI tool for syncing and managing Linear issues with local TOON format.
+Optimized Linear workflow for Claude Code — save 50%+ tokens compared to MCP.
 
-## Installation
+## Features
+
+- **Token Efficient** — Local cycle cache eliminates repeated API calls, saving 50%+ tokens vs Linear MCP
+- **Smart Task Selection** — Auto-pick highest priority unassigned work with `/work-on next`
+- **Multi-team Support** — Sync and filter issues across multiple teams
+- **Cycle History** — Local `.toon` files preserve cycle data for AI context
+- **User Filtering** — Only see issues assigned to you or unassigned
+
+## Quick Start
+
+### 1. Install & Initialize
 
 ```bash
-# npm (recommended)
 npm install -g team-toon-tack
+export LINEAR_API_KEY="lin_api_xxxxx"
 
-# Or with bun
-bun add -g team-toon-tack
+cd your-project
+ttt init
+```
 
-# Or use npx/bunx without installing
-npx team-toon-tack <command>
-bunx team-toon-tack <command>
+### 2. Setup Claude Code Commands
 
-# Short alias after global install
-ttt <command>
+```bash
+cp -r /path/to/team-toon-tack/templates/claude-code-commands/* .claude/commands/
 ```
 
-## Quick Start
+Edit `.claude/commands/work-on.md` lines 37-40 to add your project's verification steps:
 
 ```bash
-# 1. Set your Linear API key
-export LINEAR_API_KEY="lin_api_xxxxx"
+# Example: Add your checks here
+bun run typecheck
+bun run lint
+bun run test
+```
 
-# 2. Initialize in your project
-cd your-project
-ttt init
+### 3. Daily Workflow
 
-# 3. Sync issues from Linear
-ttt sync
+In Claude Code:
 
-# 4. Start working
-ttt work-on
 ```
+/sync              # Fetch all Linear issues for current cycle
+/work-on next      # Pick highest priority task & start working
+/done-job          # Complete task with AI-generated summary
+```
+
+That's it.
 
-## Commands
+---
+
+## CLI Reference
 
 ### `ttt init`
 
-Initialize configuration files in current directory.
+Initialize configuration in current directory.
 
 ```bash
 ttt init                           # Interactive mode
 ttt init --user alice@example.com  # Pre-select user
 ttt init --label Frontend          # Set default label
 ttt init --force                   # Overwrite existing config
-ttt init -y                        # Non-interactive mode
 ```
 
 ### `ttt sync`
@@ -58,7 +72,7 @@ Sync current cycle issues from Linear.
 
 ```bash
 ttt sync              # Sync all matching issues
-ttt sync MP-123       # Sync only this specific issue
+ttt sync MP-123       # Sync specific issue only
 ```
 
 ### `ttt work-on`
@@ -90,11 +104,8 @@ ttt status              # Show current in-progress task
 ttt status MP-123       # Show specific issue status
 ttt status MP-123 --set +1      # Move to next status
 ttt status MP-123 --set done    # Mark as done
-ttt status --set pending        # Reset current task
 ```
 
-Status options: `+1`, `-1`, `+2`, `-2`, `pending`, `in-progress`, `completed`, `blocked`, `todo`, `done`, `testing`
-
 ### `ttt config`
 
 Configure settings.
@@ -110,130 +121,20 @@ ttt config teams        # Configure multi-team selection
 
 ### Directory Structure
 
-After `ttt init`, your project will have:
-
 ```
 your-project/
-└── .ttt/                  # Config directory
-    ├── config.toon        # Team configuration (gitignore recommended)
-    ├── local.toon         # Personal settings (gitignore)
-    └── cycle.toon         # Current cycle data (gitignore, auto-generated)
-```
-
-### Custom Config Directory
-
-```bash
-# Use -d flag
-ttt sync -d ./team
-
-# Or set environment variable
-export TOON_DIR=./team
-ttt sync
+└── .ttt/
+    ├── config.toon     # Team config (gitignore recommended)
+    ├── local.toon      # Personal settings (gitignore)
+    └── cycle.toon      # Current cycle data (auto-generated)
 ```
 
-### config.toon
-
-Team-wide configuration (fetched from Linear):
-
-```toon
-teams:
-  main:
-    id: TEAM_UUID
-    name: Team Name
-
-users:
-  alice:
-    id: USER_UUID
-    email: alice@example.com
-    displayName: Alice
-
-labels:
-  frontend:
-    id: LABEL_UUID
-    name: Frontend
-
-current_cycle:
-  id: CYCLE_UUID
-  name: Cycle #1
-```
-
-### local.toon
-
-Personal settings:
-
-```toon
-current_user: alice
-team: frontend
-teams[2]:
-  - frontend
-  - backend
-label: Frontend
-exclude_labels[1]:
-  - Bug
-exclude_assignees[1]:
-  - bob
-```
-
-| Field | Description |
-|-------|-------------|
-| `current_user` | Your user key from config.toon |
-| `team` | Primary team key |
-| `teams` | Multiple teams to sync (optional) |
-| `label` | Filter issues by label (optional) |
-| `exclude_labels` | Exclude issues with these labels (optional) |
-| `exclude_assignees` | Hide issues from these users (optional) |
-
-### config.toon - Status Mappings
-
-Configure which Linear statuses map to local states:
-
-```toon
-status_transitions:
-  todo: Todo
-  in_progress: In Progress
-  done: Done
-  testing: Testing
-```
-
-Run `ttt config status` to configure interactively.
-
-## Environment Variables
+### Environment Variables
 
 | Variable | Description |
 |----------|-------------|
 | `LINEAR_API_KEY` | **Required.** Your Linear API key |
-| `TOON_DIR` | Config directory (default: current directory) |
-
-## Integration Examples
-
-### With Claude Code
-
-```yaml
-# .claude/commands/sync.md
----
-description: Sync Linear issues
----
-ttt sync -d team
-```
-
-### As Git Submodule
-
-```bash
-# Add config directory as submodule
-git submodule add https://github.com/your-org/team-config.git team
-cd team && ttt sync
-```
-
-### In package.json
-
-```json
-{
-  "scripts": {
-    "sync": "ttt sync -d team",
-    "work": "ttt work-on -d team"
-  }
-}
-```
+| `TOON_DIR` | Config directory (default: `.ttt`) |
 
 ## License
 

package/README.zh-TW.md

@@ -2,405 +2,77 @@
 
 繁體中文 | [English](./README.md)
 
-使用 TOON 格式同步與管理 Linear 任務的 CLI 工具。
+為 Claude Code 最佳化的 Linear 工作流 — 比 MCP 節省 50% 以上的 token。
 
-## 為什麼需要這個工具？
+## 特色功能
 
-在使用 Linear 管理專案任務時，常見的痛點：
+- **節省 Token** — 本地 cycle 快取避免重複 API 呼叫，比 Linear MCP 省 50%+ token
+- **智慧任務挑選** — `/work-on next` 自動選擇最高優先級的未指派工作
+- **多團隊支援** — 跨多個團隊同步與過濾 issue
+- **Cycle 歷史保存** — 本地 `.toon` 檔案保留 cycle 資料，方便 AI 檢閱
+- **使用者過濾** — 只顯示指派給你或未指派的工作
 
-- **AI 助手整合困難**：Claude Code 等 AI 工具無法直接讀取 Linear 的任務上下文
-- **狀態同步繁瑣**：手動在 Linear 和本地之間切換更新狀態
-- **團隊協作不透明**：難以追蹤誰在做什麼、進度如何
-
-**team-toon-tack** 解決這些問題：將 Linear 任務同步到本地 TOON 檔案，讓 AI 助手能讀取任務內容，並自動同步狀態變更。
-
-## 運作原理
-
-```
-┌─────────────┐     ┌──────────────┐     ┌─────────────┐
-│   Linear    │────▶│  ttt sync    │────▶│ cycle.toon  │
-│   (雲端)    │     │               │    │  (本地)      │
-└─────────────┘     └──────────────┘     └─────────────┘
-                                                │
-                                                ▼
-┌─────────────┐     ┌──────────────┐     ┌─────────────┐
-│   Linear    │◀────│  ttt done    │◀────│ Claude Code │
-│  狀態更新    │     │  ttt work-on │     │    讀取任務   │
-└─────────────┘     └──────────────┘     └─────────────┘
-```
-
-### 核心流程
-
-1. **同步 (sync)**
-   - 從 Linear API 抓取當前 Cycle 的任務
-   - 根據 `local.ttt` 設定過濾（標籤、排除指派人）
-   - 寫入 `cycle.toon`，包含完整任務資訊
-
-2. **開始任務 (work-on)**
-   - 讀取 `cycle.toon` 中的待處理任務
-   - 更新本地狀態為 `in-progress`
-   - 同步更新 Linear 狀態為 "In Progress"
-
-3. **完成任務 (done)**
-   - 更新本地狀態為 `completed`
-   - 同步更新 Linear 狀態為 "Done"
-   - 自動在 Linear 新增完成留言（含 commit 資訊）
-   - 若有父任務，自動更新為 "Testing"
-
-### 檔案結構與用途
-
-```
-.ttt/                    # 配置目錄（建議 gitignore）
-├── config.toon         # 團隊配置
-│   ├── teams            # Linear 團隊 ID 映射
-│   ├── users            # 成員 ID/email 映射
-│   ├── labels           # 標籤 ID 映射
-│   ├── status_transitions # 狀態映射配置
-│   └── current_cycle    # 當前 Cycle 資訊
-│
-├── local.toon          # 個人設定（必須 gitignore）
-│   ├── current_user     # 你的 user key
-│   ├── team             # 主要團隊
-│   ├── teams            # 多團隊同步（可選）
-│   ├── label            # 過濾標籤（可選）
-│   ├── exclude_labels   # 排除的標籤
-│   └── exclude_assignees # 排除的指派人
-│
-└── cycle.toon          # 任務資料（自動產生）
-    ├── cycleId          # Cycle UUID
-    ├── cycleName        # Cycle 名稱
-    ├── updatedAt        # 最後同步時間
-    └── tasks[]          # 任務列表
-        ├── id           # 任務編號 (MP-123)
-        ├── linearId     # Linear UUID
-        ├── title        # 標題
-        ├── description  # 描述（Markdown）
-        ├── status       # Linear 狀態
-        ├── localStatus  # 本地狀態
-        ├── priority     # 優先級 (1=Urgent, 4=Low)
-        ├── labels       # 標籤列表
-        ├── branch       # Git 分支名
-        ├── attachments  # 附件列表
-        └── comments     # 留言列表
-```
+## 快速開始
 
-## 安裝
+### 1. 安裝與初始化
 
 ```bash
-# npm（推薦）
 npm install -g team-toon-tack
-
-# 或用 bun
-bun add -g team-toon-tack
-```
-
-## 快速開始
-
-```bash
-# 1. 設定 Linear API 金鑰
 export LINEAR_API_KEY="lin_api_xxxxx"
 
-# 2. 初始化（會從 Linear 抓取團隊資料）
-mkdir .ttt && cd .ttt
+cd your-project
 ttt init
-
-# 3. 同步任務
-ttt sync
-
-# 4. 開始工作
-ttt work-on
 ```
 
-## 使用情境
-
-### 情境 1：每日開工流程
+### 2. 設定 Claude Code Commands
 
 ```bash
-# 早上開始工作前，同步最新任務
-ttt sync -d .ttt
-
-# 查看待處理任務並選擇一個開始
-ttt work-on -d .ttt
-
-# Claude Code 現在可以讀取任務內容
-# 在 .ttt/cycle.toon 中找到任務描述、附件等
-```
-
-### 情境 2：搭配 Claude Code 自動化
-
-建立以下三個 slash command 檔案：
-
-#### `.claude/commands/sync-linear.md`
-
-```markdown
----
-name: sync-linear
-description: Sync Linear issues to local TOON file
----
-
-# Sync Linear Issues
-
-Fetch current cycle's issues from Linear to `.ttt/cycle.toon`.
-
-## Process
-
-### 1. Run Sync
-
-\`\`\`bash
-ttt sync -d .ttt
-\`\`\`
-
-### 2. Review Output
-
-Script displays a summary of tasks in the current cycle.
-
-## When to Use
-
-- Before starting a new work session
-- When task list is missing or outdated
-- After issues are updated in Linear
-```
-
-#### `.claude/commands/work-on.md`
-
-```markdown
----
-name: work-on
-description: Select and start working on a Linear issue
-arguments:
-  - name: issue-id
-    description: "Issue ID (e.g., MP-624) or 'next' for auto-select"
-    required: false
----
-
-# Start Working on Issue
-
-Select a task and update status to "In Progress" on both local and Linear.
-
-## Process
-
-### 1. Run Command
-
-\`\`\`bash
-ttt work-on -d .ttt $ARGUMENTS
-\`\`\`
-
-### 2. Review Issue Details
-
-Script displays title, description, priority, labels, and attachments.
-
-### 3. Implement
-
-1. Read the issue description carefully
-2. Explore related code
-3. Implement the fix/feature
-4. Run validation commands
-5. Commit with conventional format
-6. Use `/done-job` to complete
-```
-
-#### `.claude/commands/done-job.md`
-
-```markdown
----
-name: done-job
-description: Mark a Linear issue as done with AI summary comment
-arguments:
-  - name: issue-id
-    description: Linear issue ID (e.g., MP-624). Optional if only one task is in-progress
-    required: false
----
-
-# Complete Task
-
-Mark a task as done and update Linear with commit details.
-
-## Process
-
-### 1. Determine Issue ID
-
-Check `.ttt/cycle.toon` for tasks with `localStatus: in-progress`.
-
-### 2. Write Fix Summary
-
-Prepare a concise summary (1-3 sentences) covering:
-- Root cause
-- How it was resolved
-- Key code changes
-
-### 3. Run Command
-
-\`\`\`bash
-ttt done -d .ttt $ARGUMENTS -m "修復說明"
-\`\`\`
-
-## What It Does
-
-- Linear issue status → "Done"
-- Adds comment with commit hash, message, and diff summary
-- Parent issue (if exists) → "Testing"
-- Local status → `completed` in `.ttt/cycle.toon`
+cp -r /path/to/team-toon-tack/templates/claude-code-commands/* .claude/commands/
 ```
 
-#### 使用方式
-
-```
-/sync-linear        # 同步任務
-/work-on            # 互動選擇任務
-/work-on MP-624     # 指定任務
-/work-on next       # 自動選最高優先級
-/done-job           # 完成當前任務
-/done-job MP-624    # 完成指定任務
-```
-
-Claude Code 會自動：
-- 執行 `ttt work-on` 開始任務
-- 讀取任務描述和附件
-- 根據需求實作功能
-- 執行 `ttt done` 更新狀態並留言
-
-### 情境 3：完成任務並自動留言
+編輯 `.claude/commands/work-on.md` 第 37-40 行，加入你專案的驗證步驟：
 
 ```bash
-# 完成開發後
-git add . && git commit -m "feat: implement feature X"
-
-# 標記任務完成，會自動在 Linear 新增留言
-ttt done -d .ttt -m "實作了 X 功能，修改了 Y 元件"
+# 範例：加入你的檢查
+bun run typecheck
+bun run lint
+bun run test
 ```
 
-Linear 上會自動新增留言：
-```markdown
-## ✅ 開發完成
-
-### 🤖 AI 修復說明
-實作了 X 功能，修改了 Y 元件
-
-### 📝 Commit Info
-**Commit:** [abc1234](https://github.com/...)
-**Message:** feat: implement feature X
+### 3. 每日工作流
 
-### 📊 Changes
- src/components/X.vue | 50 +++
- src/utils/Y.ts       | 20 +-
- 2 files changed, 60 insertions(+), 10 deletions(-)
-```
+在 Claude Code 中：
 
-### 情境 4：團隊協作過濾
-
-前端工程師只想看前端任務：
-```toon
-# local.toon
-current_user: alice
-team: frontend
-label: Frontend
-exclude_labels[1]:
-  - Bug
-exclude_assignees[2]:
-  - bob    # 排除後端同事的任務
-  - charlie
 ```
-
-後端工程師的設定（多團隊支援）：
-```toon
-# local.toon
-current_user: bob
-team: backend
-teams[2]:
-  - backend
-  - devops
-label: Backend
+/sync              # 從 Linear 取得當前 cycle 所有 issue
+/work-on next      # 挑選最高優先級任務並開始工作
+/done-job          # 完成任務，附上 AI 生成的摘要
 ```
 
-### 情境 5：狀態管理
-
-```bash
-# 查看當前進行中任務的詳細資訊
-ttt status
-
-# 查看特定任務狀態
-ttt status MP-624
-
-# 快速移動狀態
-ttt status MP-624 --set +1    # 移動到下一狀態
-
-# 配置 Linear 狀態映射
-ttt config status             # 互動式配置
+就這樣。
 
-# 配置過濾器
-ttt config filters            # 設定 exclude_labels, exclude_assignees
-```
-
-### 情境 6：多專案管理
-
-```bash
-# 專案 A
-cd project-a
-ttt sync -d .ttt
-
-# 專案 B（不同 Linear 團隊）
-cd ../project-b
-ttt init -d .ttt  # 初始化不同的配置
-ttt sync -d .ttt
-```
-
-### 情境 7：CI/CD 整合
-
-```yaml
-# .github/workflows/sync.yml
-name: Sync Linear Tasks
-on:
-  schedule:
-    - cron: '0 9 * * 1-5'  # 週一到週五早上 9 點
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm install -g team-toon-tack
-      - run: ttt sync -d .ttt
-        env:
-          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
-      - run: |
-          git add .ttt/cycle.toon
-          git commit -m "chore: sync linear tasks" || true
-          git push
-```
+---
 
-## 指令參考
+## CLI 參考
 
 ### `ttt init`
 
-初始化配置檔，從 Linear 抓取團隊資料。
+在當前目錄初始化配置。
 
 ```bash
-ttt init [options]
-
-選項：
-  -d, --dir <path>      配置目錄（預設：當前目錄）
-  -k, --api-key <key>   Linear API 金鑰
-  -u, --user <email>    預選使用者
-  -l, --label <name>    預設標籤過濾
-  -f, --force           覆蓋現有配置
-  -y, --yes             非互動模式
+ttt init                           # 互動模式
+ttt init --user alice@example.com  # 預選使用者
+ttt init --label Frontend          # 設定預設標籤
+ttt init --force                   # 覆蓋現有配置
 ```
 
 ### `ttt sync`
 
-從 Linear 同步任務到本地。
+從 Linear 同步當前 cycle 的 issue。
 
 ```bash
-ttt sync [issue-id] [options]
-
-參數：
-  issue-id              可選。只同步此特定任務（如 MP-624）
-
-選項：
-  -d, --dir <path>      配置目錄
-
-範例：
-  ttt sync              # 同步所有符合條件的任務
-  ttt sync MP-624       # 只同步此特定任務
+ttt sync              # 同步所有符合條件的 issue
+ttt sync MP-123       # 只同步特定 issue
 ```
 
 ### `ttt work-on`
@@ -408,13 +80,9 @@ ttt sync [issue-id] [options]
 開始處理任務。
 
 ```bash
-ttt work-on [issue-id] [options]
-
-參數：
-  issue-id              任務編號（如 MP-624）或 "next"
-
-選項：
-  -d, --dir <path>      配置目錄
+ttt work-on              # 互動選擇
+ttt work-on MP-123       # 指定 issue
+ttt work-on next         # 自動選擇最高優先級
 ```
 
 ### `ttt done`
@@ -422,14 +90,9 @@ ttt work-on [issue-id] [options]
 標記任務完成。
 
 ```bash
-ttt done [issue-id] [options]
-
-參數：
-  issue-id              任務編號（可選）
-
-選項：
-  -d, --dir <path>      配置目錄
-  -m, --message <msg>   完成說明
+ttt done                    # 若只有一個進行中，自動選擇
+ttt done MP-123             # 指定 issue
+ttt done -m "修復了錯誤"      # 附上完成說明
 ```
 
 ### `ttt status`
@@ -437,27 +100,10 @@ ttt done [issue-id] [options]
 顯示或修改任務狀態。
 
 ```bash
-ttt status [issue-id] [--set <status>]
-
-參數：
-  issue-id              任務編號（可選，預設顯示進行中任務）
-
-選項：
-  -s, --set <status>    設定狀態
-
-狀態選項：
-  +1, -1, +2, -2       相對移動狀態
-  pending              設為待處理
-  in-progress          設為進行中
-  completed            設為已完成
-  blocked              設為後端阻擋
-  todo, done, testing  設定 Linear 狀態
-
-範例：
-  ttt status              # 顯示當前進行中任務
-  ttt status MP-624       # 顯示特定任務狀態
-  ttt status MP-624 --set +1      # 移動到下一狀態
-  ttt status MP-624 --set done    # 標記為完成
+ttt status              # 顯示當前進行中的任務
+ttt status MP-123       # 顯示特定 issue 狀態
+ttt status MP-123 --set +1      # 移動到下一狀態
+ttt status MP-123 --set done    # 標記為完成
 ```
 
 ### `ttt config`
@@ -465,60 +111,30 @@ ttt status [issue-id] [--set <status>]
 配置設定。
 
 ```bash
-ttt config [subcommand]
-
-子指令：
-  show      顯示當前配置（預設）
-  status    配置狀態映射（todo, in_progress, done, testing）
-  filters   配置過濾器（label, exclude_labels, exclude_assignees）
-  teams     配置團隊選擇（多團隊支援）
-
-範例：
-  ttt config              # 顯示當前配置
-  ttt config status       # 配置狀態映射
-  ttt config filters      # 配置過濾器
-  ttt config teams        # 配置團隊選擇
+ttt config              # 顯示當前配置
+ttt config status       # 配置狀態映射
+ttt config filters      # 配置標籤/使用者過濾
+ttt config teams        # 配置多團隊選擇
 ```
 
-## 環境變數
-
-| 變數 | 說明 |
-|------|------|
-| `LINEAR_API_KEY` | **必填**。Linear API 金鑰（[取得方式](https://linear.app/settings/api)） |
-| `TOON_DIR` | 配置目錄路徑（可取代 `-d` 參數） |
-
-## 常見問題
-
-### Q: 為什麼用 TOON 格式？
-
-TOON 是一種人類可讀的資料格式，類似 YAML 但更簡潔。相比 JSON：
-- 更容易手動編輯
-- 支援註解
-- AI 助手更容易理解
+## 配置說明
 
-### Q: config.ttt 可以提交到 Git 嗎？
+### 目錄結構
 
-可以，但建議 gitignore。因為包含：
-- 團隊成員的 email
-- Linear 內部 UUID
-
-如果是私有倉庫且團隊成員都有 Linear 存取權，提交是安全的。
-
-### Q: 如何處理衝突？
-
-`cycle.toon` 是自動產生的，直接用 `ttt sync` 重新同步即可。
+```
+your-project/
+└── .ttt/
+    ├── config.toon     # 團隊配置（建議 gitignore）
+    ├── local.toon      # 個人設定（gitignore）
+    └── cycle.toon      # 當前 cycle 資料（自動產生）
+```
 
-### Q: 支援哪些 Linear 功能？
+### 環境變數
 
-- ✅ Cycle 任務同步
-- ✅ 單一任務同步 (`ttt sync MP-624`)
-- ✅ 狀態雙向同步
-- ✅ 自訂狀態映射（`ttt config status`）
-- ✅ 附件和留言讀取
-- ✅ 父子任務關聯
-- ✅ 優先級排序
-- ✅ 多團隊支援
-- ✅ 標籤/用戶過濾
+| 變數 | 說明 |
+|------|------|
+| `LINEAR_API_KEY` | **必填**。你的 Linear API 金鑰 |
+| `TOON_DIR` | 配置目錄（預設：`.ttt`） |
 
 ## 授權
 

package/dist/scripts/done-job.js

@@ -1,7 +1,8 @@
 import prompts from "prompts";
 import { buildCompletionComment, getLatestCommit } from "./lib/git.js";
 import { addComment, getStatusTransitions, getWorkflowStates, updateIssueStatus, } from "./lib/linear.js";
-import { getLinearClient, loadConfig, loadCycleData, loadLocalConfig, saveCycleData, } from "./utils.js";
+import { syncSingleIssue } from "./lib/sync.js";
+import { getLinearClient, loadConfig, loadCycleData, loadLocalConfig, } from "./utils.js";
 function parseArgs(args) {
     let issueId;
     let message;
@@ -144,10 +145,15 @@ Examples:
             }
         }
     }
-    // Update local status
-    task.localStatus = "completed";
-    await saveCycleData(data);
-    console.log(`Local: ${task.id} → completed`);
+    // Sync full issue data from Linear (including new comment)
+    const syncedTask = await syncSingleIssue(task.id, {
+        config,
+        localConfig,
+        preserveLocalStatus: false, // Let remote status determine local status
+    });
+    if (syncedTask) {
+        console.log(`Synced: ${syncedTask.id} → ${syncedTask.status} (local: ${syncedTask.localStatus})`);
+    }
     // Summary
     console.log(`\n${"═".repeat(50)}`);
     console.log(`✅ ${task.id}: ${task.title}`);

package/dist/scripts/init.js

@@ -208,6 +208,52 @@ async function selectStatusMappings(states, options) {
         testing: testingResponse.testing,
     };
 }
+async function updateGitignore(tttDir, interactive) {
+    const gitignorePath = ".gitignore";
+    const entry = `${tttDir}/`;
+    try {
+        let content = "";
+        let exists = false;
+        try {
+            content = await fs.readFile(gitignorePath, "utf-8");
+            exists = true;
+        }
+        catch {
+            // .gitignore doesn't exist
+        }
+        // Check if already ignored
+        const lines = content.split("\n");
+        const alreadyIgnored = lines.some((line) => line.trim() === entry ||
+            line.trim() === tttDir ||
+            line.trim() === `/${entry}` ||
+            line.trim() === `/${tttDir}`);
+        if (alreadyIgnored) {
+            return;
+        }
+        // Ask user in interactive mode
+        if (interactive) {
+            const { addToGitignore } = await prompts({
+                type: "confirm",
+                name: "addToGitignore",
+                message: `Add ${entry} to .gitignore?`,
+                initial: true,
+            });
+            if (!addToGitignore)
+                return;
+        }
+        // Add to .gitignore
+        const newContent = exists
+            ? content.endsWith("\n")
+                ? `${content}${entry}\n`
+                : `${content}\n${entry}\n`
+            : `${entry}\n`;
+        await fs.writeFile(gitignorePath, newContent, "utf-8");
+        console.log(`  ✓ Added ${entry} to .gitignore`);
+    }
+    catch (_error) {
+        // Silently ignore gitignore errors
+    }
+}
 async function init() {
     const args = process.argv.slice(2);
     const options = parseArgs(args);
@@ -338,6 +384,9 @@ async function init() {
     }
     await fs.writeFile(paths.localPath, encode(localConfig), "utf-8");
     console.log(`  ✓ ${paths.localPath}`);
+    // Update .gitignore
+    const tttDir = paths.baseDir.replace(/^\.\//, "");
+    await updateGitignore(tttDir, options.interactive ?? true);
     // Summary
     console.log("\n✅ Initialization complete!\n");
     console.log("Configuration summary:");

package/dist/scripts/lib/config-builder.js

@@ -66,8 +66,7 @@ export function getDefaultStatusTransitions(states) {
     const defaultDone = states.find((s) => s.type === "completed")?.name ||
         findStatusByKeyword(states, ["done", "complete"]) ||
         "Done";
-    const defaultTesting = findStatusByKeyword(states, ["testing", "review"]) ||
-        undefined;
+    const defaultTesting = findStatusByKeyword(states, ["testing", "review"]) || undefined;
     return {
         todo: defaultTodo,
         in_progress: defaultInProgress,

package/dist/scripts/lib/sync.d.ts

@@ -0,0 +1,13 @@
+import type { LinearClient } from "@linear/sdk";
+import { type Config, type LocalConfig, type Task } from "../utils.js";
+export interface SyncIssueOptions {
+    config: Config;
+    localConfig: LocalConfig;
+    client?: LinearClient;
+    preserveLocalStatus?: boolean;
+}
+/**
+ * Sync a single issue from Linear and update local cycle data
+ * Returns the updated task or null if issue not found
+ */
+export declare function syncSingleIssue(issueId: string, options: SyncIssueOptions): Promise<Task | null>;

package/dist/scripts/lib/sync.js

@@ -0,0 +1,97 @@
+import { getLinearClient, loadCycleData, saveCycleData, getPrioritySortIndex, } from "../utils.js";
+import { getStatusTransitions } from "./linear.js";
+/**
+ * Sync a single issue from Linear and update local cycle data
+ * Returns the updated task or null if issue not found
+ */
+export async function syncSingleIssue(issueId, options) {
+    const { config, localConfig: _localConfig, preserveLocalStatus = true, } = options;
+    const client = options.client ?? getLinearClient();
+    // Search for the issue
+    const searchResult = await client.searchIssues(issueId);
+    const matchingIssue = searchResult.nodes.find((i) => i.identifier === issueId);
+    if (!matchingIssue) {
+        console.error(`Issue ${issueId} not found in Linear.`);
+        return null;
+    }
+    // Fetch full issue data
+    const issue = await client.issue(matchingIssue.id);
+    const assignee = await issue.assignee;
+    const assigneeEmail = assignee?.email;
+    const labels = await issue.labels();
+    const labelNames = labels.nodes.map((l) => l.name);
+    const state = await issue.state;
+    const parent = await issue.parent;
+    const attachmentsData = await issue.attachments();
+    const commentsData = await issue.comments();
+    // Build attachments list
+    const attachments = attachmentsData.nodes.map((a) => ({
+        id: a.id,
+        title: a.title,
+        url: a.url,
+        sourceType: a.sourceType ?? undefined,
+    }));
+    // Build comments list
+    const comments = await Promise.all(commentsData.nodes.map(async (c) => {
+        const user = await c.user;
+        return {
+            id: c.id,
+            body: c.body,
+            createdAt: c.createdAt.toISOString(),
+            user: user?.displayName ?? user?.email,
+        };
+    }));
+    // Determine local status
+    let localStatus = "pending";
+    const existingData = await loadCycleData();
+    if (preserveLocalStatus && existingData) {
+        const existingTask = existingData.tasks.find((t) => t.id === issueId);
+        if (existingTask) {
+            localStatus = existingTask.localStatus;
+        }
+    }
+    // Map remote status to local status if not preserving
+    if (!preserveLocalStatus && state) {
+        const transitions = getStatusTransitions(config);
+        if (state.name === transitions.done) {
+            localStatus = "completed";
+        }
+        else if (state.name === transitions.in_progress) {
+            localStatus = "in-progress";
+        }
+        else {
+            localStatus = "pending";
+        }
+    }
+    const task = {
+        id: issue.identifier,
+        linearId: issue.id,
+        title: issue.title,
+        status: state ? state.name : "Unknown",
+        localStatus: localStatus,
+        assignee: assigneeEmail,
+        priority: issue.priority,
+        labels: labelNames,
+        branch: issue.branchName,
+        description: issue.description ?? undefined,
+        parentIssueId: parent ? parent.identifier : undefined,
+        url: issue.url,
+        attachments: attachments.length > 0 ? attachments : undefined,
+        comments: comments.length > 0 ? comments : undefined,
+    };
+    // Update cycle data
+    if (existingData) {
+        const existingTasks = existingData.tasks.filter((t) => t.id !== issueId);
+        const finalTasks = [...existingTasks, task];
+        // Sort by priority
+        finalTasks.sort((a, b) => {
+            const pa = getPrioritySortIndex(a.priority, config.priority_order);
+            const pb = getPrioritySortIndex(b.priority, config.priority_order);
+            return pa - pb;
+        });
+        existingData.tasks = finalTasks;
+        existingData.updatedAt = new Date().toISOString();
+        await saveCycleData(existingData);
+    }
+    return task;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "team-toon-tack",
-	"version": "1.6.3",
+	"version": "1.7.1",
 	"description": "Linear task sync & management CLI with TOON format",
 	"type": "module",
 	"bin": {