team-toon-tack 1.7.1 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wei Hung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,13 +2,18 @@
 
 [繁體中文](./README.zh-TW.md) | English
 
-Optimized Linear workflow for Claude Code — save 50%+ tokens compared to MCP.
+Optimized Linear workflow for Claude Code — saves significant tokens compared to MCP.
 
 ## Features
 
-- **Token Efficient** — Local cycle cache eliminates repeated API calls, saving 50%+ tokens vs Linear MCP
+- **Token Efficient** — Local cycle cache eliminates repeated API calls, saving significant 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
+- **Flexible Sync Modes** — Choose between remote (immediate Linear sync) or local (offline-first, sync later with `--update`)
+- **QA/PM Team Support** — Auto-update parent issues in QA/PM team to "Testing" when completing dev tasks
+- **Attachment Download** — Auto-download Linear images and files to local `.ttt/output/` for AI vision analysis
+- **Blocked Status** — Set tasks as blocked when waiting on external dependencies
+- **Auto Command Setup** — `ttt init` can install Claude Code commands with custom prefix
 - **Cycle History** — Local `.toon` files preserve cycle data for AI context
 - **User Filtering** — Only see issues assigned to you or unassigned
 
@@ -24,22 +29,12 @@ cd your-project
 ttt init
 ```
 
-### 2. Setup Claude Code Commands
+During init, you'll configure:
+- **Status source**: `remote` (update Linear immediately) or `local` (work offline, sync with `ttt sync --update`)
+- **QA/PM team**: For cross-team parent issue updates (parent must be set in Linear)
+- **Claude Code commands**: Auto-install with optional prefix (e.g., `/ttt:work-on`)
 
-```bash
-cp -r /path/to/team-toon-tack/templates/claude-code-commands/* .claude/commands/
-```
-
-Edit `.claude/commands/work-on.md` lines 37-40 to add your project's verification steps:
-
-```bash
-# Example: Add your checks here
-bun run typecheck
-bun run lint
-bun run test
-```
-
-### 3. Daily Workflow
+### 2. Daily Workflow
 
 In Claude Code:
 
@@ -73,6 +68,7 @@ Sync current cycle issues from Linear.
 ```bash
 ttt sync              # Sync all matching issues
 ttt sync MP-123       # Sync specific issue only
+ttt sync --update     # Push local status changes to Linear (for local mode)
 ```
 
 ### `ttt work-on`
@@ -104,6 +100,7 @@ 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 MP-123 --set blocked # Set as blocked (waiting on dependency)
 ```
 
 ### `ttt config`
@@ -126,7 +123,8 @@ your-project/
 └── .ttt/
     ├── config.toon     # Team config (gitignore recommended)
     ├── local.toon      # Personal settings (gitignore)
-    └── cycle.toon      # Current cycle data (auto-generated)
+    ├── cycle.toon      # Current cycle data (auto-generated)
+    └── output/         # Downloaded attachments (images, files)
 ```
 
 ### Environment Variables

package/README.zh-TW.md

@@ -2,13 +2,18 @@
 
 繁體中文 | [English](./README.md)
 
-為 Claude Code 最佳化的 Linear 工作流 — 比 MCP 節省 50% 以上的 token。
+為 Claude Code 最佳化的 Linear 工作流 — 比 MCP 節省大量 token。
 
 ## 特色功能
 
-- **節省 Token** — 本地 cycle 快取避免重複 API 呼叫，比 Linear MCP 省 50%+ token
+- **節省 Token** — 本地 cycle 快取避免重複 API 呼叫，比 Linear MCP 省下大量 token
 - **智慧任務挑選** — `/work-on next` 自動選擇最高優先級的未指派工作
 - **多團隊支援** — 跨多個團隊同步與過濾 issue
+- **彈性同步模式** — 選擇 remote（即時同步 Linear）或 local（離線優先，稍後用 `--update` 同步）
+- **QA/PM 團隊支援** — 完成開發任務時自動將 QA/PM 團隊的 parent issue 更新為「Testing」
+- **附件下載** — 自動下載 Linear 圖片和檔案到本地 `.ttt/output/`，供 AI 視覺分析
+- **阻塞狀態** — 等待外部依賴時可設定任務為 blocked
+- **自動安裝指令** — `ttt init` 可自動安裝 Claude Code commands，支援自訂前綴
 - **Cycle 歷史保存** — 本地 `.toon` 檔案保留 cycle 資料，方便 AI 檢閱
 - **使用者過濾** — 只顯示指派給你或未指派的工作
 
@@ -24,22 +29,12 @@ cd your-project
 ttt init
 ```
 
-### 2. 設定 Claude Code Commands
+初始化時會設定：
+- **狀態來源**：`remote`（即時更新 Linear）或 `local`（離線工作，用 `ttt sync --update` 同步）
+- **QA/PM 團隊**：跨團隊 parent issue 更新（需在 Linear 設定 parent）
+- **Claude Code commands**：自動安裝，可選前綴（如 `/ttt:work-on`）
 
-```bash
-cp -r /path/to/team-toon-tack/templates/claude-code-commands/* .claude/commands/
-```
-
-編輯 `.claude/commands/work-on.md` 第 37-40 行，加入你專案的驗證步驟：
-
-```bash
-# 範例：加入你的檢查
-bun run typecheck
-bun run lint
-bun run test
-```
-
-### 3. 每日工作流
+### 2. 每日工作流
 
 在 Claude Code 中：
 
@@ -73,6 +68,7 @@ ttt init --force                   # 覆蓋現有配置
 ```bash
 ttt sync              # 同步所有符合條件的 issue
 ttt sync MP-123       # 只同步特定 issue
+ttt sync --update     # 將本地狀態推送到 Linear（local 模式用）
 ```
 
 ### `ttt work-on`
@@ -104,6 +100,7 @@ ttt status              # 顯示當前進行中的任務
 ttt status MP-123       # 顯示特定 issue 狀態
 ttt status MP-123 --set +1      # 移動到下一狀態
 ttt status MP-123 --set done    # 標記為完成
+ttt status MP-123 --set blocked # 設為阻塞（等待外部依賴）
 ```
 
 ### `ttt config`
@@ -126,7 +123,8 @@ your-project/
 └── .ttt/
     ├── config.toon     # 團隊配置（建議 gitignore）
     ├── local.toon      # 個人設定（gitignore）
-    └── cycle.toon      # 當前 cycle 資料（自動產生）
+    ├── cycle.toon      # 當前 cycle 資料（自動產生）
+    └── output/         # 下載的附件（圖片、檔案）
 ```
 
 ### 環境變數

package/dist/scripts/done-job.js

@@ -104,8 +104,11 @@ Examples:
         });
         aiMessage = aiMsgResponse.aiMessage || "";
     }
-    // Update Linear
-    if (task.linearId && process.env.LINEAR_API_KEY) {
+    // Update Linear (only if status_source is 'remote' or not set)
+    const statusSource = localConfig.status_source || "remote";
+    if (task.linearId &&
+        process.env.LINEAR_API_KEY &&
+        statusSource === "remote") {
         const transitions = getStatusTransitions(config);
         // Update issue to Done
         const success = await updateIssueStatus(task.linearId, transitions.done, config, localConfig.team);
@@ -129,7 +132,20 @@ Examples:
                 if (parentIssue) {
                     const parentTeam = await parentIssue.team;
                     if (parentTeam) {
-                        const parentStates = await getWorkflowStates(config, localConfig.team);
+                        // Determine which team key to use for parent's workflow states
+                        // If qa_pm_team is configured and matches parent's team, use it
+                        // Otherwise, try to find the team key from config
+                        let parentTeamKey = localConfig.team;
+                        const teamEntries = Object.entries(config.teams);
+                        const matchingTeam = teamEntries.find(([_, t]) => t.id === parentTeam.id);
+                        if (matchingTeam) {
+                            parentTeamKey = matchingTeam[0];
+                        }
+                        else if (localConfig.qa_pm_team) {
+                            // Fallback to qa_pm_team if configured
+                            parentTeamKey = localConfig.qa_pm_team;
+                        }
+                        const parentStates = await getWorkflowStates(config, parentTeamKey);
                         const testingState = parentStates.find((s) => s.name === transitions.testing);
                         if (testingState) {
                             await client.updateIssue(parentIssue.id, {
@@ -145,6 +161,10 @@ Examples:
             }
         }
     }
+    else if (statusSource === "local") {
+        console.log(`Local: ${task.id} marked as completed`);
+        console.log(`(Linear status not updated - use 'sync --update' to push)`);
+    }
     // Sync full issue data from Linear (including new comment)
     const syncedTask = await syncSingleIssue(task.id, {
         config,

package/dist/scripts/init.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import fs from "node:fs/promises";
+import path from "node:path";
 import { decode, encode } from "@toon-format/toon";
 import prompts from "prompts";
 import { buildConfig, buildLocalConfig, findTeamKey, findUserKey, getDefaultStatusTransitions, } from "./lib/config-builder.js";
@@ -116,6 +117,40 @@ async function selectTeams(teams, options) {
     }
     return { selected: selectedTeams, primary: primaryTeam };
 }
+async function selectQaPmTeam(teams, primaryTeam, options) {
+    // Only ask if there are multiple teams and interactive mode
+    if (!options.interactive || teams.length <= 1) {
+        return undefined;
+    }
+    // Filter out primary team from choices
+    const otherTeams = teams.filter((t) => t.id !== primaryTeam.id);
+    if (otherTeams.length === 0) {
+        return undefined;
+    }
+    console.log("\n🔗 QA/PM Team Configuration:");
+    const response = await prompts({
+        type: "select",
+        name: "qaPmTeamId",
+        message: "Select QA/PM team (for cross-team parent issue updates):",
+        choices: [
+            {
+                title: "(None - skip)",
+                value: undefined,
+                description: "No cross-team parent updates",
+            },
+            ...otherTeams.map((t) => ({
+                title: t.name,
+                value: t.id,
+                description: "Parent issues in this team will be updated to Testing",
+            })),
+        ],
+        initial: 0,
+    });
+    if (!response.qaPmTeamId) {
+        return undefined;
+    }
+    return teams.find((t) => t.id === response.qaPmTeamId);
+}
 async function selectUser(users, options) {
     let currentUser = users[0];
     if (options.user) {
@@ -157,6 +192,31 @@ async function selectLabelFilter(labels, options) {
     }
     return undefined;
 }
+async function selectStatusSource(options) {
+    if (!options.interactive) {
+        return "remote"; // default
+    }
+    console.log("\n🔄 Configure status sync mode:");
+    const response = await prompts({
+        type: "select",
+        name: "statusSource",
+        message: "Where should status updates be stored?",
+        choices: [
+            {
+                title: "Remote (recommended)",
+                value: "remote",
+                description: "Update Linear immediately when you work-on or complete tasks",
+            },
+            {
+                title: "Local",
+                value: "local",
+                description: "Work offline, then sync to Linear with 'sync --update'",
+            },
+        ],
+        initial: 0,
+    });
+    return response.statusSource || "remote";
+}
 async function selectStatusMappings(states, options) {
     const defaults = getDefaultStatusTransitions(states);
     if (!options.interactive || states.length === 0) {
@@ -201,11 +261,25 @@ async function selectStatusMappings(states, options) {
             ? testingChoices.findIndex((c) => c.value === defaults.testing)
             : 0,
     });
+    const blockedChoices = [
+        { title: "(None)", value: undefined },
+        ...stateChoices,
+    ];
+    const blockedResponse = await prompts({
+        type: "select",
+        name: "blocked",
+        message: 'Select status for "Blocked" (optional, for blocked tasks):',
+        choices: blockedChoices,
+        initial: defaults.blocked
+            ? blockedChoices.findIndex((c) => c.value === defaults.blocked)
+            : 0,
+    });
     return {
         todo: todoResponse.todo || defaults.todo,
         in_progress: inProgressResponse.in_progress || defaults.in_progress,
         done: doneResponse.done || defaults.done,
         testing: testingResponse.testing,
+        blocked: blockedResponse.blocked,
     };
 }
 async function updateGitignore(tttDir, interactive) {
@@ -254,6 +328,148 @@ async function updateGitignore(tttDir, interactive) {
         // Silently ignore gitignore errors
     }
 }
+async function installClaudeCommands(interactive, statusSource) {
+    if (!interactive) {
+        return { installed: false, prefix: "" };
+    }
+    console.log("\n🤖 Claude Code Commands:");
+    // Ask if user wants to install commands
+    const { install } = await prompts({
+        type: "confirm",
+        name: "install",
+        message: "Install Claude Code commands? (work-on, done-job, sync-linear)",
+        initial: true,
+    });
+    if (!install) {
+        return { installed: false, prefix: "" };
+    }
+    // Ask for prefix
+    const { prefixChoice } = await prompts({
+        type: "select",
+        name: "prefixChoice",
+        message: "Command prefix style:",
+        choices: [
+            {
+                title: "No prefix (recommended)",
+                value: "",
+                description: "/work-on, /done-job, /sync-linear",
+            },
+            {
+                title: "ttt:",
+                value: "ttt:",
+                description: "/ttt:work-on, /ttt:done-job, /ttt:sync-linear",
+            },
+            {
+                title: "linear:",
+                value: "linear:",
+                description: "/linear:work-on, /linear:done-job, /linear:sync-linear",
+            },
+            {
+                title: "Custom...",
+                value: "custom",
+                description: "Enter your own prefix",
+            },
+        ],
+        initial: 0,
+    });
+    let prefix = prefixChoice || "";
+    if (prefixChoice === "custom") {
+        const { customPrefix } = await prompts({
+            type: "text",
+            name: "customPrefix",
+            message: "Enter custom prefix (e.g., 'my:'):",
+            initial: "",
+        });
+        prefix = customPrefix || "";
+    }
+    // Find templates directory
+    // Try multiple locations: installed package, local dev
+    const possibleTemplatePaths = [
+        path.join(__dirname, "..", "templates", "claude-code-commands"),
+        path.join(__dirname, "..", "..", "templates", "claude-code-commands"),
+        path.join(process.cwd(), "templates", "claude-code-commands"),
+    ];
+    let templateDir = null;
+    for (const p of possibleTemplatePaths) {
+        try {
+            await fs.access(p);
+            templateDir = p;
+            break;
+        }
+        catch {
+            // Try next path
+        }
+    }
+    if (!templateDir) {
+        // Try to get repo URL from package.json
+        let repoUrl = "https://github.com/wayne930242/team-toon-tack";
+        try {
+            const pkgPaths = [
+                path.join(__dirname, "..", "package.json"),
+                path.join(__dirname, "..", "..", "package.json"),
+            ];
+            for (const pkgPath of pkgPaths) {
+                try {
+                    const pkgContent = await fs.readFile(pkgPath, "utf-8");
+                    const pkg = JSON.parse(pkgContent);
+                    if (pkg.repository?.url) {
+                        // Parse git+https://github.com/user/repo.git format
+                        repoUrl = pkg.repository.url
+                            .replace(/^git\+/, "")
+                            .replace(/\.git$/, "");
+                    }
+                    break;
+                }
+                catch {
+                    // Try next path
+                }
+            }
+        }
+        catch {
+            // Use default URL
+        }
+        console.log("  ⚠ Could not find command templates. Please copy manually from:");
+        console.log(`    ${repoUrl}/tree/main/templates/claude-code-commands`);
+        return { installed: false, prefix };
+    }
+    // Create .claude/commands directory
+    const commandsDir = path.join(process.cwd(), ".claude", "commands");
+    await fs.mkdir(commandsDir, { recursive: true });
+    // Copy and rename template files
+    const templateFiles = await fs.readdir(templateDir);
+    const commandFiles = templateFiles.filter((f) => f.endsWith(".md"));
+    for (const file of commandFiles) {
+        const baseName = file.replace(".md", "");
+        const newFileName = prefix ? `${prefix}${baseName}.md` : file;
+        const srcPath = path.join(templateDir, file);
+        const destPath = path.join(commandsDir, newFileName);
+        // Read template content
+        let content = await fs.readFile(srcPath, "utf-8");
+        // Update the name in frontmatter if prefix is used
+        if (prefix) {
+            content = content.replace(/^(---\s*\n[\s\S]*?name:\s*)(\S+)/m, `$1${prefix}${baseName}`);
+        }
+        // Modify content based on statusSource for work-on and done-job
+        if (statusSource === "local") {
+            if (baseName === "work-on" || baseName.endsWith("work-on")) {
+                // Update description for local mode
+                content = content.replace(/Select a task and update status to "In Progress" on both local and Linear\./, 'Select a task and update local status to "In Progress". (Linear will be updated when you run `sync --update`)');
+                // Add reminder after Complete section
+                content = content.replace(/Use `?\/done-job`? to mark task as completed/, "Use `/done-job` to mark task as completed\n\n### 7. Sync to Linear\n\nWhen ready to update Linear with all your changes:\n\n```bash\nttt sync --update\n```");
+            }
+            if (baseName === "done-job" || baseName.endsWith("done-job")) {
+                // Update description for local mode
+                content = content.replace(/Mark a task as done and update Linear with commit details\./, "Mark a task as done locally. (Run `ttt sync --update` to push changes to Linear)");
+                // Add reminder at the end
+                content = content.replace(/## What It Does\n\n- Linear issue status → "Done"/, "## What It Does\n\n- Local status → `completed`");
+                content += `\n## Sync to Linear\n\nAfter completing tasks, push all changes to Linear:\n\n\`\`\`bash\nttt sync --update\n\`\`\`\n`;
+            }
+        }
+        await fs.writeFile(destPath, content, "utf-8");
+        console.log(`  ✓ .claude/commands/${newFileName}`);
+    }
+    return { installed: true, prefix };
+}
 async function init() {
     const args = process.argv.slice(2);
     const options = parseArgs(args);
@@ -308,24 +524,62 @@ async function init() {
     if (selectedTeams.length > 1) {
         console.log(`  Primary: ${primaryTeam.name}`);
     }
-    // Fetch data from primary team
-    const selectedTeam = await client.team(primaryTeam.id);
-    const members = await selectedTeam.members();
-    const users = members.nodes;
+    // Fetch data from ALL teams (not just primary) to support cross-team operations
+    console.log(`  Fetching data from ${teams.length} teams...`);
+    // Collect users, labels, states from all teams
+    const allUsers = [];
+    const allLabels = [];
+    const allStates = [];
+    const seenUserIds = new Set();
+    const seenLabelIds = new Set();
+    const seenStateIds = new Set();
+    for (const team of teams) {
+        try {
+            const teamData = await client.team(team.id);
+            const members = await teamData.members();
+            for (const user of members.nodes) {
+                if (!seenUserIds.has(user.id)) {
+                    seenUserIds.add(user.id);
+                    allUsers.push(user);
+                }
+            }
+            const labelsData = await client.issueLabels({
+                filter: { team: { id: { eq: team.id } } },
+            });
+            for (const label of labelsData.nodes) {
+                if (!seenLabelIds.has(label.id)) {
+                    seenLabelIds.add(label.id);
+                    allLabels.push(label);
+                }
+            }
+            const statesData = await client.workflowStates({
+                filter: { team: { id: { eq: team.id } } },
+            });
+            for (const state of statesData.nodes) {
+                if (!seenStateIds.has(state.id)) {
+                    seenStateIds.add(state.id);
+                    allStates.push(state);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`  ⚠ Could not fetch data for team ${team.name}, skipping...`);
+        }
+    }
+    const users = allUsers;
+    const labels = allLabels;
+    const states = allStates;
     console.log(`  Users: ${users.length}`);
-    const labelsData = await client.issueLabels({
-        filter: { team: { id: { eq: primaryTeam.id } } },
-    });
-    const labels = labelsData.nodes;
     console.log(`  Labels: ${labels.length}`);
-    const statesData = await client.workflowStates({
-        filter: { team: { id: { eq: primaryTeam.id } } },
-    });
-    const states = statesData.nodes;
+    console.log(`  Workflow states: ${states.length}`);
+    // Get cycle from primary team (for current work tracking)
+    const selectedTeam = await client.team(primaryTeam.id);
     const currentCycle = (await selectedTeam.activeCycle);
     // User selections
     const currentUser = await selectUser(users, options);
     const defaultLabel = await selectLabelFilter(labels, options);
+    const statusSource = await selectStatusSource(options);
+    const qaPmTeam = await selectQaPmTeam(teams, primaryTeam, options);
     const statusTransitions = await selectStatusMappings(states, options);
     // Build config
     const config = buildConfig(teams, users, labels, states, statusTransitions, currentCycle ?? undefined);
@@ -335,7 +589,11 @@ async function init() {
     const selectedTeamKeys = selectedTeams
         .map((team) => findTeamKey(config.teams, team.id))
         .filter((key) => key !== undefined);
-    const localConfig = buildLocalConfig(currentUserKey, primaryTeamKey, selectedTeamKeys, defaultLabel);
+    const qaPmTeamKey = qaPmTeam
+        ? findTeamKey(config.teams, qaPmTeam.id)
+        : undefined;
+    const localConfig = buildLocalConfig(currentUserKey, primaryTeamKey, selectedTeamKeys, defaultLabel, undefined, // excludeLabels
+    statusSource, qaPmTeamKey);
     // Write config files
     console.log("\n📝 Writing configuration files...");
     await fs.mkdir(paths.baseDir, { recursive: true });
@@ -372,10 +630,14 @@ async function init() {
                     localConfig.team = existingLocal.team;
                 if (existingLocal.teams)
                     localConfig.teams = existingLocal.teams;
+                if (existingLocal.qa_pm_team)
+                    localConfig.qa_pm_team = existingLocal.qa_pm_team;
                 if (existingLocal.label)
                     localConfig.label = existingLocal.label;
                 if (existingLocal.exclude_labels)
                     localConfig.exclude_labels = existingLocal.exclude_labels;
+                if (existingLocal.status_source)
+                    localConfig.status_source = existingLocal.status_source;
             }
         }
         catch {
@@ -387,6 +649,8 @@ async function init() {
     // Update .gitignore
     const tttDir = paths.baseDir.replace(/^\.\//, "");
     await updateGitignore(tttDir, options.interactive ?? true);
+    // Install Claude Code commands
+    const { installed: commandsInstalled, prefix: commandPrefix } = await installClaudeCommands(options.interactive ?? true, statusSource);
     // Summary
     console.log("\n✅ Initialization complete!\n");
     console.log("Configuration summary:");
@@ -396,6 +660,10 @@ async function init() {
     }
     console.log(`  User: ${currentUser.displayName || currentUser.name} (${currentUser.email})`);
     console.log(`  Label filter: ${defaultLabel || "(none)"}`);
+    console.log(`  Status source: ${statusSource === "local" ? "local (use 'sync --update' to push)" : "remote (immediate sync)"}`);
+    if (qaPmTeam) {
+        console.log(`  QA/PM team: ${qaPmTeam.name}`);
+    }
     console.log(`  (Use 'ttt config filters' to set excluded labels/users)`);
     if (currentCycle) {
         console.log(`  Cycle: ${currentCycle.name || `Cycle #${currentCycle.number}`}`);
@@ -407,10 +675,24 @@ async function init() {
     if (statusTransitions.testing) {
         console.log(`    Testing: ${statusTransitions.testing}`);
     }
+    if (statusTransitions.blocked) {
+        console.log(`    Blocked: ${statusTransitions.blocked}`);
+    }
+    if (commandsInstalled) {
+        const cmdPrefix = commandPrefix ? `${commandPrefix}` : "";
+        console.log(`  Claude commands: /${cmdPrefix}work-on, /${cmdPrefix}done-job, /${cmdPrefix}sync-linear`);
+    }
     console.log("\nNext steps:");
     console.log("  1. Set LINEAR_API_KEY in your shell profile:");
     console.log(`     export LINEAR_API_KEY="${apiKey}"`);
-    console.log("  2. Run sync: bun run sync");
-    console.log("  3. Start working: bun run work-on");
+    console.log("  2. Run sync: ttt sync");
+    if (commandsInstalled) {
+        const cmdPrefix = commandPrefix ? `${commandPrefix}` : "";
+        console.log(`  3. In Claude Code: /${cmdPrefix}work-on next`);
+        console.log(`\n💡 Tip: Edit .claude/commands/${cmdPrefix}work-on.md to customize the "Verify" section for your project.`);
+    }
+    else {
+        console.log("  3. Start working: ttt work-on");
+    }
 }
 init().catch(console.error);

package/dist/scripts/lib/config-builder.d.ts

@@ -38,4 +38,4 @@ export declare function getDefaultStatusTransitions(states: LinearState[]): Stat
 export declare function buildConfig(teams: LinearTeam[], users: LinearUser[], labels: LinearLabel[], states: LinearState[], statusTransitions: StatusTransitions, currentCycle?: LinearCycle): Config;
 export declare function findUserKey(usersConfig: Record<string, UserConfig>, userId: string): string;
 export declare function findTeamKey(teamsConfig: Record<string, TeamConfig>, teamId: string): string;
-export declare function buildLocalConfig(currentUserKey: string, primaryTeamKey: string, selectedTeamKeys: string[], defaultLabel?: string, excludeLabels?: string[]): LocalConfig;
+export declare function buildLocalConfig(currentUserKey: string, primaryTeamKey: string, selectedTeamKeys: string[], defaultLabel?: string, excludeLabels?: string[], statusSource?: "remote" | "local", qaPmTeam?: string): LocalConfig;

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

@@ -67,11 +67,13 @@ export function getDefaultStatusTransitions(states) {
         findStatusByKeyword(states, ["done", "complete"]) ||
         "Done";
     const defaultTesting = findStatusByKeyword(states, ["testing", "review"]) || undefined;
+    const defaultBlocked = findStatusByKeyword(states, ["blocked", "on hold", "waiting"]) || undefined;
     return {
         todo: defaultTodo,
         in_progress: defaultInProgress,
         done: defaultDone,
         testing: defaultTesting,
+        blocked: defaultBlocked,
     };
 }
 export function buildConfig(teams, users, labels, states, statusTransitions, currentCycle) {
@@ -106,12 +108,14 @@ export function findTeamKey(teamsConfig, teamId) {
     return (Object.entries(teamsConfig).find(([_, t]) => t.id === teamId)?.[0] ||
         Object.keys(teamsConfig)[0]);
 }
-export function buildLocalConfig(currentUserKey, primaryTeamKey, selectedTeamKeys, defaultLabel, excludeLabels) {
+export function buildLocalConfig(currentUserKey, primaryTeamKey, selectedTeamKeys, defaultLabel, excludeLabels, statusSource, qaPmTeam) {
     return {
         current_user: currentUserKey,
         team: primaryTeamKey,
         teams: selectedTeamKeys.length > 1 ? selectedTeamKeys : undefined,
+        qa_pm_team: qaPmTeam,
         label: defaultLabel,
         exclude_labels: excludeLabels && excludeLabels.length > 0 ? excludeLabels : undefined,
+        status_source: statusSource,
     };
 }

package/dist/scripts/lib/display.js

@@ -11,7 +11,7 @@ export function getStatusIcon(localStatus) {
             return "✅";
         case "in-progress":
             return "🔄";
-        case "blocked-backend":
+        case "blocked":
             return "🚫";
         default:
             return "📋";
@@ -39,14 +39,25 @@ export function displayTaskStatus(task) {
 }
 export function displayTaskDescription(task) {
     if (task.description) {
-        console.log(`\n📝 Description:\n${task.description}`);
+        let description = task.description;
+        // Replace Linear URLs with local paths from attachments
+        if (task.attachments) {
+            for (const att of task.attachments) {
+                if (att.localPath && att.url) {
+                    description = description.split(att.url).join(att.localPath);
+                }
+            }
+        }
+        console.log(`\n📝 Description:\n${description}`);
     }
 }
 export function displayTaskAttachments(task) {
     if (task.attachments && task.attachments.length > 0) {
         console.log(`\n📎 Attachments:`);
         for (const att of task.attachments) {
-            console.log(`   - ${att.title}: ${att.url}`);
+            // Prefer local path for Linear images (Linear URLs are not accessible)
+            const displayPath = att.localPath || att.url;
+            console.log(`   - ${att.title}: ${displayPath}`);
         }
     }
 }

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

@@ -0,0 +1,9 @@
+export declare function isLinearImageUrl(url: string): boolean;
+/**
+ * Extract Linear image URLs from markdown text (description, comments)
+ */
+export declare function extractLinearImageUrls(text: string): string[];
+export declare function downloadLinearFile(url: string, issueId: string, attachmentId: string, outputDir: string): Promise<string | undefined>;
+export declare const downloadLinearImage: typeof downloadLinearFile;
+export declare function clearIssueImages(outputDir: string, issueId: string): Promise<void>;
+export declare function ensureOutputDir(outputDir: string): Promise<void>;

package/dist/scripts/lib/images.js

@@ -0,0 +1,107 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const LINEAR_IMAGE_DOMAINS = [
+    "uploads.linear.app",
+    "linear-uploads.s3.us-west-2.amazonaws.com",
+];
+export function isLinearImageUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return LINEAR_IMAGE_DOMAINS.some((domain) => parsed.host.includes(domain));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract Linear image URLs from markdown text (description, comments)
+ */
+export function extractLinearImageUrls(text) {
+    const urls = [];
+    // Match markdown image syntax ![alt](url) and plain URLs
+    const patterns = [
+        /!\[[^\]]*\]\((https?:\/\/[^)]+)\)/g, // ![alt](url)
+        /(https?:\/\/uploads\.linear\.app\/[^\s)>\]]+)/g, // Plain Linear upload URLs
+    ];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const url = match[1];
+            if (isLinearImageUrl(url) && !urls.includes(url)) {
+                urls.push(url);
+            }
+        }
+    }
+    return urls;
+}
+function getFileExtension(url, contentType) {
+    // Try to get extension from content-type header
+    if (contentType) {
+        // Image types
+        const imageMatch = contentType.match(/image\/(\w+)/);
+        if (imageMatch) {
+            const ext = imageMatch[1] === "jpeg" ? "jpg" : imageMatch[1];
+            return { ext, isImage: true };
+        }
+        // Video types
+        const videoMatch = contentType.match(/video\/(\w+)/);
+        if (videoMatch) {
+            const videoExt = videoMatch[1] === "quicktime" ? "mov" : videoMatch[1];
+            return { ext: videoExt, isImage: false };
+        }
+    }
+    // Fallback: try to get from URL path
+    const urlPath = new URL(url).pathname;
+    const ext = path.extname(urlPath).slice(1).toLowerCase();
+    if (["jpg", "jpeg", "png", "gif", "webp", "svg"].includes(ext)) {
+        return { ext: ext === "jpeg" ? "jpg" : ext, isImage: true };
+    }
+    if (["mov", "mp4", "webm", "avi"].includes(ext)) {
+        return { ext, isImage: false };
+    }
+    return { ext: "png", isImage: true }; // Default assume image
+}
+export async function downloadLinearFile(url, issueId, attachmentId, outputDir) {
+    try {
+        // Linear files require authentication
+        const headers = {};
+        if (process.env.LINEAR_API_KEY) {
+            headers["Authorization"] = process.env.LINEAR_API_KEY;
+        }
+        const response = await fetch(url, { headers });
+        if (!response.ok) {
+            console.error(`Failed to download file: ${response.status}`);
+            return undefined;
+        }
+        const contentType = response.headers.get("content-type") || undefined;
+        const { ext } = getFileExtension(url, contentType);
+        const filename = `${issueId}_${attachmentId}.${ext}`;
+        const filepath = path.join(outputDir, filename);
+        const buffer = await response.arrayBuffer();
+        await fs.writeFile(filepath, Buffer.from(buffer));
+        return filepath;
+    }
+    catch (error) {
+        console.error(`Error downloading file: ${error}`);
+        return undefined;
+    }
+}
+// Alias for backwards compatibility
+export const downloadLinearImage = downloadLinearFile;
+export async function clearIssueImages(outputDir, issueId) {
+    try {
+        const files = await fs.readdir(outputDir);
+        const issuePrefix = `${issueId}_`;
+        for (const file of files) {
+            if (file.startsWith(issuePrefix)) {
+                await fs.unlink(path.join(outputDir, file));
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or other error, ignore
+    }
+}
+export async function ensureOutputDir(outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+}

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

@@ -8,4 +8,4 @@ export declare function getWorkflowStates(config: Config, teamKey: string): Prom
 export declare function getStatusTransitions(config: Config): StatusTransitions;
 export declare function updateIssueStatus(linearId: string, targetStatusName: string, config: Config, teamKey: string): Promise<boolean>;
 export declare function addComment(issueId: string, body: string): Promise<boolean>;
-export declare function mapLocalStatusToLinear(localStatus: "pending" | "in-progress" | "completed" | "blocked-backend", config: Config): string | undefined;
+export declare function mapLocalStatusToLinear(localStatus: "pending" | "in-progress" | "completed" | "blocked", config: Config): string | undefined;

package/dist/scripts/lib/linear.js

@@ -55,6 +55,8 @@ export function mapLocalStatusToLinear(localStatus, config) {
             return transitions.in_progress;
         case "completed":
             return transitions.done;
+        case "blocked":
+            return transitions.blocked;
         default:
             return undefined;
     }

package/dist/scripts/status.js

@@ -6,7 +6,7 @@ const LOCAL_STATUS_ORDER = [
     "pending",
     "in-progress",
     "completed",
-    "blocked-backend",
+    "blocked",
 ];
 function parseArgs(args) {
     let issueId;
@@ -41,7 +41,7 @@ Options:
                         pending  Set to pending
                         in-progress  Set to in-progress
                         completed    Set to completed
-                        blocked      Set to blocked-backend
+                        blocked      Set to blocked (syncs to Linear if configured)
                         todo     Set Linear to Todo status
                         done     Set Linear to Done status
 
@@ -105,17 +105,8 @@ Examples:
             const newIndex = Math.max(currentIndex - 2, 0);
             newLocalStatus = LOCAL_STATUS_ORDER[newIndex];
         }
-        else if ([
-            "pending",
-            "in-progress",
-            "completed",
-            "blocked-backend",
-            "blocked",
-        ].includes(setStatus)) {
-            newLocalStatus =
-                setStatus === "blocked"
-                    ? "blocked-backend"
-                    : setStatus;
+        else if (["pending", "in-progress", "completed", "blocked"].includes(setStatus)) {
+            newLocalStatus = setStatus;
         }
         else if (["todo", "in_progress", "done", "testing"].includes(setStatus)) {
             const transitions = getStatusTransitions(config);
@@ -143,8 +134,9 @@ Examples:
             task.localStatus = newLocalStatus;
             needsSave = true;
         }
-        // Update Linear status
-        if (newLinearStatus || newLocalStatus) {
+        // Update Linear status (only if status_source is 'remote' or not set)
+        const statusSource = localConfig.status_source || "remote";
+        if (statusSource === "remote" && (newLinearStatus || newLocalStatus)) {
             let targetStateName = newLinearStatus;
             if (!targetStateName && newLocalStatus) {
                 targetStateName = mapLocalStatusToLinear(newLocalStatus, config);
@@ -158,12 +150,20 @@ Examples:
                 }
             }
         }
+        else if (statusSource === "local" &&
+            (newLinearStatus || newLocalStatus)) {
+            // Local mode: just note that Linear wasn't updated
+            needsSave = true;
+        }
         // Save if anything changed
         if (needsSave) {
             await saveCycleData(data);
             if (newLocalStatus && newLocalStatus !== oldLocalStatus) {
                 console.log(`Local: ${task.id} ${oldLocalStatus} → ${newLocalStatus}`);
             }
+            if (statusSource === "local") {
+                console.log(`(Linear status not updated - use 'sync --update' to push)`);
+            }
         }
         else if (newLocalStatus) {
             console.log(`Local: ${task.id} already ${newLocalStatus}`);

package/dist/scripts/sync.js

@@ -1,15 +1,20 @@
-import { getLinearClient, getPrioritySortIndex, getTeamId, loadConfig, loadCycleData, loadLocalConfig, saveConfig, saveCycleData, } from "./utils.js";
+import { getLinearClient, getPaths, getPrioritySortIndex, getTeamId, loadConfig, loadCycleData, loadLocalConfig, saveConfig, saveCycleData, } from "./utils.js";
+import { clearIssueImages, downloadLinearImage, ensureOutputDir, extractLinearImageUrls, isLinearImageUrl, } from "./lib/images.js";
 async function sync() {
     const args = process.argv.slice(2);
     // Handle help flag
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`Usage: ttt sync [issue-id]
+        console.log(`Usage: ttt sync [issue-id] [--update]
 
 Sync issues from Linear to local cycle.ttt file.
 
 Arguments:
   issue-id    Optional. Sync only this specific issue (e.g., MP-624)
 
+Options:
+  --update    Push local status changes to Linear (for local mode users)
+              This updates Linear with your local in-progress/completed statuses
+
 What it does:
   - Fetches active cycle from Linear
   - Downloads all issues matching configured filters
@@ -19,15 +24,21 @@ What it does:
 Examples:
   ttt sync              # Sync all matching issues
   ttt sync MP-624       # Sync only this specific issue
+  ttt sync --update     # Push local changes to Linear, then sync
   ttt sync -d .ttt     # Sync using .ttt directory`);
         process.exit(0);
     }
+    // Check for --update flag
+    const shouldUpdate = args.includes("--update");
     // Parse issue ID argument (if provided)
     const singleIssueId = args.find((arg) => !arg.startsWith("-") && arg.match(/^[A-Z]+-\d+$/i));
     const config = await loadConfig();
     const localConfig = await loadLocalConfig();
     const client = getLinearClient();
     const teamId = getTeamId(config, localConfig.team);
+    const { outputPath } = getPaths();
+    // Ensure output directory exists
+    await ensureOutputDir(outputPath);
     // Build excluded labels set
     const excludedLabels = new Set(localConfig.exclude_labels ?? []);
     // Phase 1: Fetch active cycle directly from team
@@ -91,6 +102,50 @@ Examples:
     const testingStateId = statusTransitions.testing
         ? stateMap.get(statusTransitions.testing)
         : undefined;
+    const inProgressStateId = stateMap.get(statusTransitions.in_progress);
+    // Phase 2.5: Push local status changes to Linear (if --update flag)
+    if (shouldUpdate && existingData) {
+        console.log("Pushing local status changes to Linear...");
+        let pushCount = 0;
+        for (const task of existingData.tasks) {
+            // Map local status to Linear status
+            let targetStateId;
+            if (task.localStatus === "in-progress" && inProgressStateId) {
+                // Check if Linear status is not already in-progress
+                if (task.status !== statusTransitions.in_progress) {
+                    targetStateId = inProgressStateId;
+                }
+            }
+            else if (task.localStatus === "completed" && testingStateId) {
+                // Check if Linear status is not already testing/done
+                const terminalStatuses = [statusTransitions.done];
+                if (statusTransitions.testing)
+                    terminalStatuses.push(statusTransitions.testing);
+                if (!terminalStatuses.includes(task.status)) {
+                    targetStateId = testingStateId;
+                }
+            }
+            if (targetStateId) {
+                try {
+                    await client.updateIssue(task.linearId, { stateId: targetStateId });
+                    const targetName = targetStateId === inProgressStateId
+                        ? statusTransitions.in_progress
+                        : statusTransitions.testing;
+                    console.log(`  ${task.id} → ${targetName}`);
+                    pushCount++;
+                }
+                catch (e) {
+                    console.error(`  Failed to update ${task.id}:`, e);
+                }
+            }
+        }
+        if (pushCount > 0) {
+            console.log(`Pushed ${pushCount} status updates to Linear.`);
+        }
+        else {
+            console.log("No local changes to push.");
+        }
+    }
     // Phase 3: Build existing tasks map for preserving local status
     const existingTasksMap = new Map(existingData?.tasks.map((t) => [t.id, t]));
     // Phase 4: Fetch current issues with full content
@@ -145,13 +200,49 @@ Examples:
         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,
-        }));
+        // Clear old images for this issue before downloading new ones
+        await clearIssueImages(outputPath, issue.identifier);
+        // Build attachments list and download Linear images
+        const attachments = [];
+        for (const a of attachmentsData.nodes) {
+            const attachment = {
+                id: a.id,
+                title: a.title,
+                url: a.url,
+                sourceType: a.sourceType ?? undefined,
+            };
+            // Download Linear domain images
+            if (isLinearImageUrl(a.url)) {
+                const localPath = await downloadLinearImage(a.url, issue.identifier, a.id, outputPath);
+                if (localPath) {
+                    attachment.localPath = localPath;
+                }
+            }
+            attachments.push(attachment);
+        }
+        // Extract and download images from description
+        if (issue.description) {
+            const descriptionImageUrls = extractLinearImageUrls(issue.description);
+            for (const url of descriptionImageUrls) {
+                // Generate a short ID from URL (last segment of path)
+                const urlPath = new URL(url).pathname;
+                const segments = urlPath.split("/").filter(Boolean);
+                const imageId = segments[segments.length - 1] || `desc_${Date.now()}`;
+                // Skip if already in attachments
+                if (attachments.some((a) => a.url === url))
+                    continue;
+                const localPath = await downloadLinearImage(url, issue.identifier, imageId, outputPath);
+                if (localPath) {
+                    attachments.push({
+                        id: imageId,
+                        title: `Description Image`,
+                        url: url,
+                        sourceType: "description",
+                        localPath: localPath,
+                    });
+                }
+            }
+        }
         // Build comments list
         const comments = await Promise.all(commentsData.nodes.map(async (c) => {
             const user = await c.user;

package/dist/scripts/utils.d.ts

@@ -4,6 +4,7 @@ export declare function getPaths(): {
     configPath: string;
     cyclePath: string;
     localPath: string;
+    outputPath: string;
 };
 export interface TeamConfig {
     id: string;
@@ -32,6 +33,7 @@ export interface StatusTransitions {
     in_progress: string;
     done: string;
     testing?: string;
+    blocked?: string;
 }
 export interface Config {
     teams: Record<string, TeamConfig>;
@@ -58,6 +60,7 @@ export interface Attachment {
     title: string;
     url: string;
     sourceType?: string;
+    localPath?: string;
 }
 export interface Comment {
     id: string;
@@ -70,7 +73,7 @@ export interface Task {
     linearId: string;
     title: string;
     status: string;
-    localStatus: "pending" | "in-progress" | "completed" | "blocked-backend";
+    localStatus: "pending" | "in-progress" | "completed" | "blocked";
     assignee?: string;
     priority: number;
     labels: string[];
@@ -92,8 +95,10 @@ export interface LocalConfig {
     current_user: string;
     team: string;
     teams?: string[];
+    qa_pm_team?: string;
     exclude_labels?: string[];
     label?: string;
+    status_source?: "remote" | "local";
 }
 export declare function fileExists(filePath: string): Promise<boolean>;
 export declare function loadConfig(): Promise<Config>;

package/dist/scripts/utils.js

@@ -19,12 +19,14 @@ const BASE_DIR = getBaseDir();
 const CONFIG_PATH = path.join(BASE_DIR, "config.toon");
 const CYCLE_PATH = path.join(BASE_DIR, "cycle.toon");
 const LOCAL_PATH = path.join(BASE_DIR, "local.toon");
+const OUTPUT_PATH = path.join(BASE_DIR, "output");
 export function getPaths() {
     return {
         baseDir: BASE_DIR,
         configPath: CONFIG_PATH,
         cyclePath: CYCLE_PATH,
         localPath: LOCAL_PATH,
+        outputPath: OUTPUT_PATH,
     };
 }
 // Linear priority value to name mapping (fixed by Linear API)

package/dist/scripts/work-on.js

@@ -83,8 +83,11 @@ Examples:
     // Mark as In Progress
     if (task.localStatus === "pending") {
         task.localStatus = "in-progress";
-        // Update Linear
-        if (task.linearId && process.env.LINEAR_API_KEY) {
+        // Update Linear (only if status_source is 'remote' or not set)
+        const statusSource = localConfig.status_source || "remote";
+        if (statusSource === "remote" &&
+            task.linearId &&
+            process.env.LINEAR_API_KEY) {
             const transitions = getStatusTransitions(config);
             const success = await updateIssueStatus(task.linearId, transitions.in_progress, config, localConfig.team);
             if (success) {
@@ -94,6 +97,9 @@ Examples:
         }
         await saveCycleData(data);
         console.log(`Local: ${task.id} → in-progress`);
+        if (statusSource === "local") {
+            console.log(`(Linear status not updated - use 'sync --update' to push)`);
+        }
     }
     // Display task info
     displayTaskFull(task, "👷");

package/package.json

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

package/templates/claude-code-commands/work-on.md

@@ -30,7 +30,17 @@ Script displays title, description, priority, labels, and attachments.
 3. Implement the fix/feature
 4. Commit with conventional format
 
-### 4. Verify
+### 4. Handle Blockers (if any)
+
+If you encounter a blocker (waiting for backend, design, external dependency):
+
+```bash
+ttt status --set blocked
+```
+
+Add a comment explaining the blocker, then move to another task.
+
+### 5. Verify
 
 Run project-required verification before completing:
 
@@ -39,7 +49,7 @@ Run project-required verification before completing:
 # (e.g., type-check, lint, test, build)
 ```
 
-### 5. Complete
+### 6. Complete
 
 Use `/done-job` to mark task as completed