team-toon-tack 2.0.3 → 2.3.0

package/dist/scripts/lib/images.js

@@ -24,12 +24,13 @@ export function extractLinearImageUrls(text) {
         /(https?:\/\/uploads\.linear\.app\/[^\s)>\]]+)/g, // Plain Linear upload URLs
     ];
     for (const pattern of patterns) {
-        let match;
-        while ((match = pattern.exec(text)) !== null) {
+        let match = pattern.exec(text);
+        while (match) {
             const url = match[1];
             if (isLinearImageUrl(url) && !urls.includes(url)) {
                 urls.push(url);
             }
+            match = pattern.exec(text);
         }
     }
     return urls;
@@ -66,7 +67,7 @@ export async function downloadLinearFile(url, issueId, attachmentId, outputDir)
         // Linear files require authentication
         const headers = {};
         if (process.env.LINEAR_API_KEY) {
-            headers["Authorization"] = process.env.LINEAR_API_KEY;
+            headers.Authorization = process.env.LINEAR_API_KEY;
         }
         const response = await fetch(url, { headers });
         if (!response.ok) {

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

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

package/dist/scripts/lib/sync.js

@@ -1,17 +1,15 @@
-import { getLinearClient, loadCycleData, saveCycleData, getPrioritySortIndex, } from "../utils.js";
+import { getLinearClient, getPrioritySortIndex, loadCycleData, saveCycleData, } 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
+ * Fetch issue details from Linear without saving to local data
+ * Returns Task object or null if issue not found
  */
-export async function syncSingleIssue(issueId, options) {
-    const { config, localConfig: _localConfig, preserveLocalStatus = true, } = options;
+export async function fetchIssueDetail(issueId, 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
@@ -41,34 +39,12 @@ export async function syncSingleIssue(issueId, options) {
             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,
+        localStatus: "pending", // Default, will be overridden by sync if needed
         assignee: assigneeEmail,
         priority: issue.priority,
         labels: labelNames,
@@ -79,6 +55,42 @@ export async function syncSingleIssue(issueId, options) {
         attachments: attachments.length > 0 ? attachments : undefined,
         comments: comments.length > 0 ? comments : undefined,
     };
+    return task;
+}
+/**
+ * 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();
+    // Fetch issue details using shared function
+    const task = await fetchIssueDetail(issueId, { client });
+    if (!task) {
+        console.error(`Issue ${issueId} not found in Linear.`);
+        return null;
+    }
+    // Determine local status
+    const existingData = await loadCycleData();
+    if (preserveLocalStatus && existingData) {
+        const existingTask = existingData.tasks.find((t) => t.id === issueId);
+        if (existingTask) {
+            task.localStatus = existingTask.localStatus;
+        }
+    }
+    // Map remote status to local status if not preserving
+    if (!preserveLocalStatus) {
+        const transitions = getStatusTransitions(config);
+        if (task.status === transitions.done) {
+            task.localStatus = "completed";
+        }
+        else if (task.status === transitions.in_progress) {
+            task.localStatus = "in-progress";
+        }
+        else {
+            task.localStatus = "pending";
+        }
+    }
     // Update cycle data
     if (existingData) {
         const existingTasks = existingData.tasks.filter((t) => t.id !== issueId);

package/dist/scripts/sync.js

@@ -1,5 +1,5 @@
-import { getLinearClient, getPaths, getPrioritySortIndex, getTeamId, loadConfig, loadCycleData, loadLocalConfig, saveConfig, saveCycleData, } from "./utils.js";
 import { clearIssueImages, downloadLinearImage, ensureOutputDir, extractLinearImageUrls, isLinearImageUrl, } from "./lib/images.js";
+import { getLinearClient, getPaths, getPrioritySortIndex, getTeamId, loadConfig, loadCycleData, loadLocalConfig, saveConfig, saveCycleData, } from "./utils.js";
 async function sync() {
     const args = process.argv.slice(2);
     // Handle help flag

package/dist/scripts/utils.d.ts

@@ -35,6 +35,11 @@ export interface StatusTransitions {
     testing?: string;
     blocked?: string;
 }
+export interface QaPmTeamConfig {
+    team: string;
+    testing_status: string;
+}
+export type CompletionMode = "simple" | "strict_review" | "upstream_strict" | "upstream_not_strict";
 export interface Config {
     teams: Record<string, TeamConfig>;
     users: Record<string, UserConfig>;
@@ -94,11 +99,14 @@ export interface CycleData {
 export interface LocalConfig {
     current_user: string;
     team: string;
-    teams?: string[];
-    qa_pm_team?: string;
+    dev_testing_status?: string;
+    qa_pm_teams?: QaPmTeamConfig[];
+    completion_mode?: CompletionMode;
     exclude_labels?: string[];
     label?: string;
     status_source?: "remote" | "local";
+    teams?: string[];
+    qa_pm_team?: string;
 }
 export declare function fileExists(filePath: string): Promise<boolean>;
 export declare function loadConfig(): Promise<Config>;

package/dist/scripts/work-on.js

@@ -1,5 +1,5 @@
 import prompts from "prompts";
-import { PRIORITY_LABELS, displayTaskFull } from "./lib/display.js";
+import { displayTaskFull, PRIORITY_LABELS } from "./lib/display.js";
 import { getStatusTransitions, updateIssueStatus } from "./lib/linear.js";
 import { getPrioritySortIndex, loadConfig, loadCycleData, loadLocalConfig, saveCycleData, } from "./utils.js";
 async function workOn() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "team-toon-tack",
-	"version": "2.0.3",
+	"version": "2.3.0",
 	"description": "Linear task sync & management CLI with TOON format",
 	"type": "module",
 	"bin": {
@@ -13,12 +13,14 @@
 	},
 	"files": [
 		"dist",
-		"templates"
+		".claude-plugin",
+		"commands",
+		"skills"
 	],
 	"scripts": {
 		"build": "tsc",
 		"lint": "biome lint .",
-		"format": "biome format --write .",
+		"format": "biome check --write .",
 		"type": "tsc --noEmit",
 		"prepublishOnly": "npm run build",
 		"release": "npm config set //registry.npmjs.org/:_authToken=$NPM_PUBLISH_KEY && npm publish"

package/skills/linear-task-manager/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: linear-task-manager
+description: Linear task management expert using ttt CLI. Manages task workflow, syncs issues, tracks status. Use when working with Linear issues, starting tasks, completing work, or checking task status.
+---
+
+# Linear Task Manager
+
+You are a Linear task management expert using the team-toon-tack (ttt) CLI tool.
+
+## Your Role
+
+Help developers efficiently manage their Linear workflow:
+- Sync issues from Linear to local cache
+- Start working on tasks
+- Track and update task status
+- Complete tasks with proper documentation
+- Fetch issue details on demand
+
+## Prerequisites
+
+Ensure the project has:
+1. `LINEAR_API_KEY` environment variable set
+2. `.ttt/` directory initialized (run `ttt init` if not)
+3. `ttt` CLI installed (`npm install -g team-toon-tack`)
+
+## Core Workflows
+
+### 1. Starting a Work Session
+
+```bash
+# Sync latest issues from Linear
+ttt sync
+
+# Pick a task to work on (interactive or auto-select)
+ttt work-on next
+# or
+ttt work-on MP-624
+```
+
+### 2. During Development
+
+```bash
+# Check current task status
+ttt status
+
+# Get full issue details
+ttt get-issue MP-624
+
+# Mark task as blocked if waiting on dependency
+ttt status MP-624 --set blocked
+```
+
+### 3. Completing Work
+
+```bash
+# Ensure code is committed first
+git add . && git commit -m "feat: implement feature"
+
+# Mark task as done with message
+ttt done -m "Implemented feature with full test coverage"
+```
+
+### 4. Syncing Changes
+
+```bash
+# Pull latest from Linear
+ttt sync
+
+# Push local status changes to Linear (if using local mode)
+ttt sync --update
+```
+
+## Status Flow
+
+```
+pending → in-progress → completed
+              ↓
+           blocked
+```
+
+### Local Status vs Linear Status
+
+| Local Status | Linear Status |
+|--------------|---------------|
+| pending | Todo |
+| in-progress | In Progress |
+| completed | Done / Testing |
+| blocked | (configurable) |
+
+## Completion Modes
+
+The `ttt done` command behaves differently based on configured mode:
+
+| Mode | Task Action | Parent Action |
+|------|-------------|---------------|
+| `simple` | → Done | → Done |
+| `strict_review` | → Testing | → QA Testing |
+| `upstream_strict` | → Done | → Testing |
+| `upstream_not_strict` | → Done | → Testing (no fallback) |
+
+## File Structure
+
+```
+.ttt/
+├── config.toon     # Team configuration
+├── local.toon      # Personal settings
+├── cycle.toon      # Current cycle tasks (auto-generated)
+└── output/         # Downloaded attachments
+```
+
+## Best Practices
+
+### DO
+- Always `ttt sync` before starting work
+- Use `ttt work-on next` for auto-prioritization
+- Include meaningful messages with `ttt done -m "..."`
+- Check `ttt status` to verify state before commits
+
+### DON'T
+- Don't manually edit `cycle.toon` - use CLI commands
+- Don't skip sync - local data may be stale
+- Don't forget to commit before `ttt done`
+
+## Troubleshooting
+
+### "No cycle data found"
+Run `ttt sync` to fetch issues from Linear.
+
+### "Issue not found in current cycle"
+The issue may not match filters. Check:
+- Issue is in active cycle
+- Issue status is Todo or In Progress
+- Issue matches configured label filter
+
+### "LINEAR_API_KEY not set"
+```bash
+export LINEAR_API_KEY="lin_api_xxxxx"
+```
+
+## Examples
+
+### Example: Start Daily Work
+```bash
+ttt sync                    # Get latest issues
+ttt work-on next           # Auto-select highest priority
+# Read task details displayed
+git checkout -b feature/mp-624-new-feature
+# Start coding...
+```
+
+### Example: Complete and Move On
+```bash
+git add . && git commit -m "feat: add new feature"
+ttt done -m "Added feature with tests"
+ttt work-on next           # Move to next task
+```
+
+### Example: Check Specific Issue
+```bash
+ttt get-issue MP-624       # Fetch from Linear
+ttt get-issue MP-624 --local  # Show cached data
+```
+
+## Important Rules
+
+- Always verify `LINEAR_API_KEY` is set before operations
+- Run `ttt sync` at the start of each work session
+- Commit code before running `ttt done`
+- Use `--local` flag to avoid API calls when checking cached data
+- Check `.ttt/output/` for downloaded attachments and images

package/templates/claude-code-commands/done-job.md

@@ -1,45 +0,0 @@
----
-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 `.toon/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 `.toon/cycle.toon`
-
-## Example Usage
-
-```
-/done-job MP-624
-/done-job
-```

package/templates/claude-code-commands/sync-linear.md

@@ -1,32 +0,0 @@
----
-name: sync-linear
-description: Sync Linear Frontend issues to local TOON file
----
-
-# Sync Linear Issues
-
-Fetch current cycle's Frontend issues from Linear to `.toon/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
-
-## Example Usage
-
-```
-/sync-linear
-```

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

@@ -1,62 +0,0 @@
----
-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. Commit with conventional format
-
-### 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:
-
-```bash
-# Run verification procedure defined in project
-# (e.g., type-check, lint, test, build)
-```
-
-### 6. Complete
-
-Use `/done-job` to mark task as completed
-
-## Example Usage
-
-```
-/work-on
-/work-on MP-624
-/work-on next
-```

package/templates/config.example.toon

@@ -1,37 +0,0 @@
-# Linear Team Configuration
-# Copy this file to config.toon and fill in your team's data
-# Run `ttt init` to generate this interactively
-
-teams:
-  main:
-    id: YOUR_TEAM_UUID
-    name: Your Team Name
-    icon: Terminal
-
-users:
-  user1:
-    id: USER1_UUID
-    email: user1@example.com
-    displayName: User One
-    role: Developer
-
-# Status mapping for Linear integration
-status_transitions:
-  todo: Todo
-  in_progress: In Progress
-  done: Done
-  testing: Testing
-
-# Priority ordering (optional, defaults shown)
-priority_order[1]: urgent
-priority_order[2]: high
-priority_order[3]: medium
-priority_order[4]: low
-priority_order[5]: none
-
-# Current cycle info (auto-managed by sync)
-# current_cycle:
-#   id: CYCLE_UUID
-#   name: Cycle #1
-#   start_date: 2026-01-01
-#   end_date: 2026-01-07

package/templates/local.example.toon

@@ -1,16 +0,0 @@
-# Local Configuration
-# Copy this file to local.toon and customize for your setup
-# This file is gitignored and contains personal settings
-
-# Your user key (must match a key in config.toon users section)
-# Only tasks assigned to this user will be synced
-current_user: user1
-
-# Primary team (required)
-team: main
-
-# Filter issues by label (optional)
-label: Frontend
-
-# Exclude issues with these labels (optional)
-# exclude_labels[1]: Backend