team-toon-tack 3.7.2 → 3.7.4

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
 	},
 	"metadata": {
 		"description": "Task management tools for Claude Code - supports Linear and Trello, efficient workflow without MCP overhead",
-		"version": "1.1.0"
+		"version": "1.2.0"
 	},
 	"plugins": [
 		{
 			"name": "team-toon-tack",
 			"source": "./",
 			"description": "Linear/Trello task sync & management CLI with commands and skills",
-			"version": "2.7.0"
+			"version": "2.8.0"
 		}
 	]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"name": "team-toon-tack",
 	"description": "Linear/Trello task sync & management CLI for Claude Code - saves tokens vs MCP",
-	"version": "2.7.0",
+	"version": "2.8.0",
 	"author": {
 		"name": "wayne930242",
 		"email": "wayne930242@gmail.com"

package/commands/ttt-work-on.md

@@ -48,30 +48,68 @@ Options:
   --dry-run   Pick task without changing status (preview only)
 ```
 
-## After Execution
+## Workflow — Plan → Test → Code → Review
 
-1. Read the task description and requirements from the output
-2. Check out the suggested branch: `git checkout -b <branch-name>`
-3. Check for project-specific **work-on skill** in `.claude/skills/`
-4. Begin implementation
+Follow this loop for every task.
+Skipping phases is not "pragmatic", it is debt.
 
-## CRITICAL: Task Completion Contract
+### 1. Branch
 
-When the task is completed, you MUST execute:
-
-```
-/ttt:done -m "completion summary"
+```bash
+git checkout -b <suggested-branch-name>
 ```
 
-A task is NOT complete until `/ttt:done` is executed. Do NOT skip this step.
+### 2. Plan
+
+Scope decides depth.
+
+- Unclear requirements or 3+ files touched → invoke `superpowers:brainstorming`, then `superpowers:writing-plans`.
+- Clear and small (≤2 files, obvious change) → state a 2–3 bullet plan inline before coding.
+
+Never go straight to code.
+Planning collapses ambiguity before implementation.
+
+### 3. Test First (TDD)
+
+Invoke `superpowers:test-driven-development`.
+
+Red → Green → Refactor per behavior:
+
+1. Write one failing test naming the behavior.
+2. Run test — verify it fails for the expected reason.
+3. Write minimal code to pass.
+4. Run test — verify pass, other tests still green.
+5. Refactor if needed, keep green.
+
+No production code without a failing test first.
+
+### 4. Review (before `/ttt:done`)
+
+Invoke `superpowers:verification-before-completion`.
+
+Run and confirm output:
+
+- Full test suite passes.
+- `npm run lint` / `npm run type` clean (or project-specific commands).
+- Only requested scope changed — no drive-by edits.
+- No debug logs, stubs, TODOs.
+
+Evidence before assertions.
+Do not claim complete without running the commands.
+
+### 5. Complete
+
+```text
+/ttt:done -m "summary"
+```
 
-## Work-On Skill Integration
+A task is NOT complete until `/ttt:done` runs.
+This is MANDATORY.
 
-After starting a task, check for project-specific work guidelines:
+## Project-Specific Skill
 
-1. Look for `work-on` or `start-work` skills in `.claude/skills/`
-2. If found, follow those guidelines
-3. If not found, suggest creating one with `/ttt:write-work-on-skill`
+Check `.claude/skills/work-on/` or `.claude/skills/start-work/` for project-specific lint / type / test commands and conventions.
+If missing, suggest `/ttt:write-work-on-skill` — it scaffolds a skill following this same 4-phase structure.
 
 ## Error Handling
 

package/commands/ttt-write-work-on-skill.md

@@ -44,68 +44,71 @@ Look for: `lint`, `type-check`, `test`, `check`, `validate`, `format`
 
 ### 4. Create Skill File
 
-Create `.claude/skills/{{ $1 | default: "work-on" }}/SKILL.md`:
+Create `.claude/skills/{{ $1 | default: "work-on" }}/SKILL.md` using the Plan → Test → Code → Review structure:
 
 ```markdown
 ---
 name: {{ $1 | default: "work-on" }}
-description: Project-specific best practices for starting and completing tasks
+description: Project workflow — Plan → Test → Code → Review. Invoke after ttt work-on picks a task.
 ---
 
-# Work-On Skill
+# Work-On Skill ({{ project-name }})
 
-Best practices for working on tasks in this project.
+Follow Plan → Test → Code → Review for every task.
+Skipping phases is debt, not pragmatism.
 
-## Before Starting
+## 1. Plan
 
-### 1. Validation Checks
-\`\`\`bash
-{{ lint-command }}
-{{ type-check-command }}
-\`\`\`
+- Unclear scope or 3+ files → use `superpowers:brainstorming` → `superpowers:writing-plans`.
+- Small, clear change → state a 2–3 bullet plan inline before coding.
 
-### 2. Branch Naming
-- Feature: `feature/<issue-id>-<short-description>`
-- Bugfix: `fix/<issue-id>-<short-description>`
-- Refactor: `refactor/<issue-id>-<short-description>`
+Branch naming:
+- `feature/<issue-id>-<slug>`
+- `fix/<issue-id>-<slug>`
+- `refactor/<issue-id>-<slug>`
 
-### 3. Environment Setup
-- Ensure dependencies are installed
-- Check for required environment variables
+## 2. Test First (TDD)
 
-## Code Style
+Invoke `superpowers:test-driven-development`.
+No production code without a failing test first.
 
-### Formatting
-{{ formatting-rules }}
+Red → Green → Refactor:
+\`\`\`bash
+{{ test-command }}
+\`\`\`
 
-### Naming Conventions
-{{ naming-conventions }}
+- One behavior per test.
+- Real code, mocks only when unavoidable.
+- Watch each test fail for the expected reason before writing code.
 
-### File Structure
-{{ file-structure-notes }}
+## 3. Code
 
-## Before Completing
+Minimal code to pass the current test.
+No features beyond the test's scope.
+Match existing style — do not refactor adjacent code.
 
-### 1. Run All Checks
-\`\`\`bash
-{{ combined-validation-command }}
-\`\`\`
+## 4. Review (before `/ttt:done`)
 
-### 2. Commit Message Format
-\`\`\`
-<type>(<scope>): <description>
+Invoke `superpowers:verification-before-completion`.
+Run every command and confirm the actual output.
 
-<body>
+\`\`\`bash
+{{ lint-command }}
+{{ type-check-command }}
+{{ test-command }}
 \`\`\`
 
-Types: feat, fix, refactor, docs, test, chore
+Checklist:
+- [ ] All tests pass (new tests went red → green).
+- [ ] No lint / type errors.
+- [ ] Changes scoped to this task only.
+- [ ] No debug logs, stubs, TODOs, commented-out code.
+- [ ] Commit message: `<type>(<scope>): <description>` — types: feat, fix, refactor, docs, test, chore.
+
+## 5. Complete
 
-### 3. Self-Review Checklist
-- [ ] Code compiles without errors
-- [ ] All tests pass
-- [ ] No linting errors
-- [ ] Changes are focused on the task
-- [ ] No debug code or console.logs left
+\`/ttt:done -m "summary"\` — MANDATORY.
+A task is NOT complete until `/ttt:done` runs.
 ```
 
 ### 5. Output

package/dist/scripts/sync.js

@@ -1,7 +1,7 @@
 import { createAdapter } from "./lib/adapters/index.js";
 import { clearAllOutput, clearIssueImages, downloadLinearImage, downloadTrelloFile, ensureOutputDir, extractImageUrls, isLinearImageUrl, } from "./lib/files.js";
 import { getReviewStatuses, getSyncStatuses, resolveLocalStatus, } from "./lib/status-helpers.js";
-import { getLinearClient, getPaths, getPrioritySortIndex, getSourceType, getTeamId, loadConfig, loadCycleData, loadLocalConfig, preserveLocalTaskFields, saveConfig, saveCycleData, } from "./utils.js";
+import { getLinearClient, getPaths, getPrioritySortIndex, getSourceType, getTeamId, loadConfig, loadCycleData, loadLocalConfig, preserveLocalTaskFields, saveConfig, saveCycleData, withRetry, } from "./utils.js";
 async function downloadEmbeddedImages(texts, issueId, attachments, outputDir, downloadFile, titlePrefix, sourceType, filterUrl) {
     let imageIndex = 0;
     for (const text of texts) {
@@ -86,56 +86,56 @@ Examples:
     }
     // Build excluded labels set
     const excludedLabels = new Set(localConfig.exclude_labels ?? []);
-    // Phase 1: Fetch active cycle directly from team
+    // Phase 1: Fetch active cycle directly from team (if the team uses cycles)
     console.log("Fetching latest cycle...");
-    const team = await client.team(teamId);
-    const activeCycle = await team.activeCycle;
-    if (!activeCycle) {
-        console.error("No active cycle found.");
-        process.exit(1);
-    }
-    const cycleId = activeCycle.id;
-    const cycleName = activeCycle.name ?? `Cycle #${activeCycle.number}`;
-    const newCycleInfo = {
-        id: cycleId,
-        name: cycleName,
-        start_date: activeCycle.startsAt?.toISOString().split("T")[0] ?? "",
-        end_date: activeCycle.endsAt?.toISOString().split("T")[0] ?? "",
-    };
-    // Check if cycle changed and update config with history
+    const team = await withRetry(() => client.team(teamId), {
+        label: "fetch team",
+    });
+    const activeCycle = await withRetry(async () => team.activeCycle ?? undefined, { label: "fetch active cycle" });
+    let cycleId;
+    let cycleName;
     const existingData = await loadCycleData();
-    const oldCycleId = config.current_cycle?.id ?? existingData?.cycleId;
-    if (oldCycleId && oldCycleId !== cycleId) {
-        const oldCycleName = config.current_cycle?.name ?? existingData?.cycleName ?? "Unknown";
-        console.log(`Cycle changed: ${oldCycleName} → ${cycleName}`);
-        // Move old cycle to history (avoid duplicates)
-        if (config.current_cycle) {
-            config.cycle_history = config.cycle_history ?? [];
-            // Remove if already exists in history
-            config.cycle_history = config.cycle_history.filter((c) => c.id !== config.current_cycle?.id);
-            config.cycle_history.unshift(config.current_cycle);
-            // Keep only last 10 cycles
-            if (config.cycle_history.length > 10) {
-                config.cycle_history = config.cycle_history.slice(0, 10);
+    if (activeCycle) {
+        cycleId = activeCycle.id;
+        cycleName = activeCycle.name ?? `Cycle #${activeCycle.number}`;
+        const newCycleInfo = {
+            id: cycleId,
+            name: cycleName,
+            start_date: activeCycle.startsAt?.toISOString().split("T")[0] ?? "",
+            end_date: activeCycle.endsAt?.toISOString().split("T")[0] ?? "",
+        };
+        const oldCycleId = config.current_cycle?.id ?? existingData?.cycleId;
+        if (oldCycleId && oldCycleId !== cycleId) {
+            const oldCycleName = config.current_cycle?.name ?? existingData?.cycleName ?? "Unknown";
+            console.log(`Cycle changed: ${oldCycleName} → ${cycleName}`);
+            if (config.current_cycle) {
+                config.cycle_history = config.cycle_history ?? [];
+                config.cycle_history = config.cycle_history.filter((c) => c.id !== config.current_cycle?.id);
+                config.cycle_history.unshift(config.current_cycle);
+                if (config.cycle_history.length > 10) {
+                    config.cycle_history = config.cycle_history.slice(0, 10);
+                }
             }
-        }
-        // Update current cycle
-        config.current_cycle = newCycleInfo;
-        await saveConfig(config);
-        console.log("Config updated with new cycle (old cycle saved to history).");
-    }
-    else {
-        // Update current cycle info even if ID unchanged (dates might change)
-        if (!config.current_cycle || config.current_cycle.id !== cycleId) {
             config.current_cycle = newCycleInfo;
             await saveConfig(config);
+            console.log("Config updated with new cycle (old cycle saved to history).");
+        }
+        else {
+            if (!config.current_cycle || config.current_cycle.id !== cycleId) {
+                config.current_cycle = newCycleInfo;
+                await saveConfig(config);
+            }
+            console.log(`Current cycle: ${cycleName}`);
         }
-        console.log(`Current cycle: ${cycleName}`);
+    }
+    else {
+        cycleName = "No Cycle";
+        console.log("No active cycle on this team — syncing without cycle filter.");
     }
     // Phase 2: Fetch workflow states and get status mappings
-    const workflowStates = await client.workflowStates({
+    const workflowStates = await withRetry(() => client.workflowStates({
         filter: { team: { id: { eq: teamId } } },
-    });
+    }), { label: "fetch workflow states" });
     const stateMap = new Map(workflowStates.nodes.map((s) => [s.name, s.id]));
     // Get status names from config or use defaults
     const statusTransitions = config.status_transitions || {
@@ -172,9 +172,9 @@ Examples:
             }
             if (targetStateId) {
                 try {
-                    const payload = await client.updateIssue(task.linearId, {
+                    const payload = await withRetry(() => client.updateIssue(task.linearId, {
                         stateId: targetStateId,
-                    });
+                    }), { label: `update ${task.id}` });
                     if (!payload.success) {
                         throw new Error("Linear mutation returned success=false");
                     }
@@ -208,7 +208,7 @@ Examples:
     if (singleIssueId) {
         // Sync single issue by ID
         console.log(`Fetching issue ${singleIssueId}...`);
-        const searchResult = await client.searchIssues(singleIssueId);
+        const searchResult = await withRetry(() => client.searchIssues(singleIssueId), { label: `search ${singleIssueId}` });
         const matchingIssue = searchResult.nodes.find((i) => i.identifier === singleIssueId);
         if (!matchingIssue) {
             console.error(`Issue ${singleIssueId} not found.`);
@@ -222,22 +222,24 @@ Examples:
             ? "all statuses"
             : `${syncStatuses.join("/")} status`;
         console.log(`Fetching issues (${statusDesc})${labelDesc}...`);
-        // Build filter - label is optional
+        // Build filter - label is optional; cycle is skipped if team has no
+        // active cycle (Linear lets teams disable cycles entirely).
         const issueFilter = {
             team: { id: { eq: teamId } },
-            cycle: { id: { eq: cycleId } },
         };
-        // Only filter by status if not syncing all
+        if (cycleId) {
+            issueFilter.cycle = { id: { eq: cycleId } };
+        }
         if (!syncAll) {
             issueFilter.state = { name: { in: syncStatuses } };
         }
         if (filterLabels && filterLabels.length > 0) {
             issueFilter.labels = { name: { in: filterLabels } };
         }
-        issues = await client.issues({
+        issues = await withRetry(() => client.issues({
             filter: issueFilter,
             first: 50,
-        });
+        }), { label: "fetch issues" });
     }
     if (issues.nodes.length === 0) {
         console.log(`No issues found in current cycle${labelDesc}.`);
@@ -253,19 +255,34 @@ Examples:
         processedCount++;
         process.stdout.write(`\r  Processing ${processedCount}/${totalIssues}...`);
         // Fetch full issue to get all relations (searchIssues returns IssueSearchResult which lacks some methods)
-        const issue = await client.issue(issueNode.id);
-        const assignee = await issue.assignee;
+        const issueLabel = issueNode.identifier;
+        const issue = await withRetry(() => client.issue(issueNode.id), {
+            label: `fetch ${issueLabel}`,
+        });
+        const assignee = await withRetry(() => Promise.resolve(issue.assignee), {
+            label: `fetch ${issueLabel} assignee`,
+        });
         const assigneeEmail = assignee?.email;
-        const labels = await issue.labels();
+        const labels = await withRetry(() => issue.labels(), {
+            label: `fetch ${issueLabel} labels`,
+        });
         const labelNames = labels.nodes.map((l) => l.name);
         // Skip if any label is in excluded list
         if (labelNames.some((name) => excludedLabels.has(name))) {
             continue;
         }
-        const state = await issue.state;
-        const parent = await issue.parent;
-        const attachmentsData = await issue.attachments();
-        const commentsData = await issue.comments();
+        const state = await withRetry(() => Promise.resolve(issue.state), {
+            label: `fetch ${issueLabel} state`,
+        });
+        const parent = await withRetry(() => Promise.resolve(issue.parent), {
+            label: `fetch ${issueLabel} parent`,
+        });
+        const attachmentsData = await withRetry(() => issue.attachments(), {
+            label: `fetch ${issueLabel} attachments`,
+        });
+        const commentsData = await withRetry(() => issue.comments(), {
+            label: `fetch ${issueLabel} comments`,
+        });
         // Clear old images for this issue before downloading new ones
         await clearIssueImages(outputPath, issue.identifier);
         // Build attachments list and download Linear images
@@ -288,7 +305,9 @@ Examples:
         }
         // Build comments list
         const comments = await Promise.all(commentsData.nodes.map(async (c) => {
-            const user = await c.user;
+            const user = await withRetry(() => Promise.resolve(c.user), {
+                label: `fetch ${issueLabel} comment user`,
+            });
             return {
                 id: c.id,
                 body: c.body,
@@ -316,9 +335,9 @@ Examples:
                 const isTerminal = terminalStates.includes(state.name) || state.type === "cancelled";
                 if (!isTerminal) {
                     console.log(`Updating ${issue.identifier} to ${statusTransitions.testing} in Linear...`);
-                    const payload = await client.updateIssue(issue.id, {
+                    const payload = await withRetry(() => client.updateIssue(issue.id, {
                         stateId: testingStateId,
-                    });
+                    }), { label: `update ${issue.identifier}` });
                     if (!payload.success) {
                         throw new Error("Linear mutation returned success=false");
                     }
@@ -372,7 +391,7 @@ Examples:
         finalTasks = tasks;
     }
     const newData = {
-        cycleId: cycleId,
+        cycleId: cycleId ?? `team:${teamId}`,
         cycleName: cycleName,
         updatedAt: new Date().toISOString(),
         tasks: finalTasks,

package/dist/scripts/utils.d.ts

@@ -141,6 +141,10 @@ export declare function getUserEmails(): Promise<string[]>;
 /** @deprecated Use getUserEmails() instead. Returns first user email for backwards compatibility. */
 export declare function getUserEmail(): Promise<string>;
 export declare function getLinearClient(): LinearClient;
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: {
+    retries?: number;
+    label?: string;
+}): Promise<T>;
 export declare function loadCycleData(): Promise<CycleData | null>;
 export declare function saveCycleData(data: CycleData): Promise<void>;
 export declare function saveConfig(config: Config): Promise<void>;

package/dist/scripts/utils.js

@@ -133,6 +133,46 @@ export function getLinearClient() {
     }
     return new LinearClient({ apiKey });
 }
+const TRANSIENT_PATTERN = /terminated|socket|ECONN|ETIMEDOUT|ENETUNREACH|ENOTFOUND|EAI_AGAIN|UND_ERR|fetch failed|other side closed|network|timeout|502|503|504/i;
+function isTransientError(err) {
+    if (!err)
+        return false;
+    const e = err;
+    const parts = [
+        typeof e.message === "string" ? e.message : "",
+        typeof e.cause?.message === "string" ? e.cause.message : "",
+        typeof e.raw?.message === "string" ? e.raw.message : "",
+        typeof e.raw?.cause?.message === "string" ? e.raw.cause.message : "",
+        typeof e.type === "string" ? e.type : "",
+    ];
+    const status = typeof e.status === "number" ? e.status : 0;
+    if (status >= 500 && status < 600)
+        return true;
+    if (status === 429)
+        return true;
+    return TRANSIENT_PATTERN.test(parts.join(" "));
+}
+export async function withRetry(fn, opts = {}) {
+    const retries = opts.retries ?? 4;
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isTransientError(err) || attempt === retries)
+                throw err;
+            const delay = Math.min(2 ** attempt * 500, 8000) + Math.random() * 250;
+            const msg = err?.message ?? String(err);
+            if (opts.label) {
+                process.stdout.write(`\n  [retry ${attempt + 1}/${retries}] ${opts.label}: ${msg.slice(0, 120)}\n`);
+            }
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw lastErr;
+}
 export async function loadCycleData() {
     try {
         await fs.access(CYCLE_PATH);

package/package.json

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

package/skills/managing-linear-tasks/SKILL.md

@@ -88,3 +88,50 @@ ttt sync → ttt work-on next → ttt estimate <id> <hours> → [implement] →
 | Issue not found locally | `ttt show <id> --remote` or `ttt sync <id>` (`ttt status` auto-fetches from remote) |
 | API key not set | Set `LINEAR_API_KEY` or `TRELLO_API_KEY` + `TRELLO_TOKEN` |
 | Stale data | `ttt sync` to refresh |
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "I'll edit `cycle.toon` directly, faster" | `cycle.toon` is auto-generated. Manual edits get overwritten on next `ttt sync`. Always go through the CLI. |
+| "I remember this issue ID, no need to sync" | Remote status, assignee, priority may have changed. Run `ttt sync` or `ttt show <id> --remote` first. |
+| "I'll create the issue in the Linear/Trello UI instead" | Bypassing `ttt create` leaves the new issue outside local cycle data. Use the CLI so it gets tracked. |
+| "Task is obvious, skip `/ttt:done`" | `/ttt:done` syncs local + remote status, posts a completion comment, reads git commit info. Skipping leaves state inconsistent. |
+| "I know what the task needs without reading it" | Fabricated assumptions produce wrong work. Run `ttt show <id>` before starting. |
+| "Fetch issue details via Linear MCP / web UI" | The CLI is authoritative and token-efficient. Use `ttt show` / `ttt sync`, not alternate data paths. |
+
+## Flowchart — Intent Routing
+
+```dot
+digraph ttt_router {
+    rankdir=LR;
+
+    user [label="User mentions\nLinear/Trello", shape=doublecircle];
+    classify [label="Classify intent", shape=diamond];
+
+    sync     [label="/ttt:sync",    shape=box];
+    show     [label="/ttt:show",    shape=box];
+    work_on  [label="/ttt:work-on", shape=box];
+    create   [label="/ttt:create",  shape=box];
+    assign   [label="/ttt:assign",  shape=box];
+    edit     [label="/ttt:edit",    shape=box];
+    cancel   [label="/ttt:cancel",  shape=box];
+    estimate [label="/ttt:estimate", shape=box];
+    status   [label="/ttt:status",  shape=box];
+    comment  [label="/ttt:comment", shape=box];
+    done     [label="/ttt:done",    shape=box];
+
+    user -> classify;
+    classify -> sync     [label="fetch / pull"];
+    classify -> show     [label="show / list"];
+    classify -> work_on  [label="start / next"];
+    classify -> create   [label="create / new"];
+    classify -> assign   [label="assign / reassign"];
+    classify -> edit     [label="rename / change field"];
+    classify -> cancel   [label="cancel / abandon"];
+    classify -> estimate [label="estimate / Nh"];
+    classify -> status   [label="current / set status"];
+    classify -> comment  [label="comment / note"];
+    classify -> done     [label="done / complete"];
+}
+```