team-toon-tack 2.1.0 → 2.3.0

package/dist/scripts/init.js

@@ -400,147 +400,39 @@ async function updateGitignore(tttDir, interactive) {
         // Silently ignore gitignore errors
     }
 }
-async function installClaudeCommands(interactive, statusSource) {
+async function showPluginInstallInstructions(interactive) {
     if (!interactive) {
-        return { installed: false, prefix: "" };
+        return false;
     }
-    console.log("\n🤖 Claude Code Commands:");
-    // Ask if user wants to install commands
-    const { install } = await prompts({
+    console.log("\n🤖 Claude Code Plugin:");
+    const { showInstructions } = await prompts({
         type: "confirm",
-        name: "install",
-        message: "Install Claude Code commands? (work-on, done-job, sync-linear)",
+        name: "showInstructions",
+        message: "Show Claude Code plugin installation instructions? (provides /ttt-* commands)",
         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 };
+    if (!showInstructions) {
+        return false;
+    }
+    console.log("\n┌─────────────────────────────────────────────────────────────┐");
+    console.log("│  Install team-toon-tack plugin in Claude Code:             │");
+    console.log("├─────────────────────────────────────────────────────────────┤");
+    console.log("│                                                             │");
+    console.log("│  1. Add marketplace:                                        │");
+    console.log("│     /plugin marketplace add wayne930242/team-toon-tack      │");
+    console.log("│                                                             │");
+    console.log("│  2. Install plugin:                                         │");
+    console.log("│     /plugin install team-toon-tack@wayne930242              │");
+    console.log("│                                                             │");
+    console.log("│  Available commands after install:                          │");
+    console.log("│     /ttt-sync        - Sync Linear issues                   │");
+    console.log("│     /ttt-work-on     - Start working on a task              │");
+    console.log("│     /ttt-done        - Complete current task                │");
+    console.log("│     /ttt-status      - Show/modify task status              │");
+    console.log("│     /ttt-get-issue   - Fetch issue details                  │");
+    console.log("│                                                             │");
+    console.log("└─────────────────────────────────────────────────────────────┘");
+    return true;
 }
 async function init() {
     const args = process.argv.slice(2);
@@ -732,8 +624,8 @@ async function init() {
     console.log(`  ✓ ${paths.localPath}`);
     // Update .gitignore (always use relative path .ttt)
     await updateGitignore(".ttt", options.interactive ?? true);
-    // Install Claude Code commands
-    const { installed: commandsInstalled, prefix: commandPrefix } = await installClaudeCommands(options.interactive ?? true, statusSource);
+    // Show Claude Code plugin installation instructions
+    const pluginInstructionsShown = await showPluginInstallInstructions(options.interactive ?? true);
     // Summary
     console.log("\n✅ Initialization complete!\n");
     console.log("Configuration summary:");
@@ -762,21 +654,13 @@ async function init() {
     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: 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");
+    console.log("  3. Start working: ttt work-on");
+    if (pluginInstructionsShown) {
+        console.log("\n💡 Tip: Install the Claude Code plugin for /ttt-* commands.");
     }
 }
 init().catch(console.error);

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

@@ -1,4 +1,4 @@
-import type { CompletionMode, Config, LocalConfig, QaPmTeamConfig, StatusTransitions, TeamConfig, UserConfig, LabelConfig } from "../utils.js";
+import type { CompletionMode, Config, LabelConfig, LocalConfig, QaPmTeamConfig, StatusTransitions, TeamConfig, UserConfig } from "../utils.js";
 export interface LinearTeam {
     id: string;
     name: string;

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/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.1.0",
+	"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
-```