team-toon-tack 1.7.0 → 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,54 +2,63 @@
 
 [繁體中文](./README.zh-TW.md) | English
 
-CLI tool for syncing and managing Linear issues with local TOON format.
+Optimized Linear workflow for Claude Code — saves significant tokens compared to MCP.
 
-## Installation
+## Features
 
-```bash
-# npm (recommended)
-npm install -g team-toon-tack
-
-# Or with bun
-bun add -g team-toon-tack
-
-# Or use npx/bunx without installing
-npx team-toon-tack <command>
-bunx team-toon-tack <command>
-
-# Short alias after global install
-ttt <command>
-```
+- **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
 
 ## Quick Start
 
+### 1. Install & Initialize
+
 ```bash
-# 1. Set your Linear API key
+npm install -g team-toon-tack
 export LINEAR_API_KEY="lin_api_xxxxx"
 
-# 2. Initialize in your project
 cd your-project
 ttt init
+```
 
-# 3. Sync issues from Linear
-ttt sync
+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`)
 
-# 4. Start working
-ttt work-on
+### 2. Daily Workflow
+
+In Claude Code:
+
+```
+/sync              # Fetch all Linear issues for current cycle
+/work-on next      # Pick highest priority task & start working
+/done-job          # Complete task with AI-generated summary
 ```
 
-## Commands
+That's it.
+
+---
+
+## CLI Reference
 
 ### `ttt init`
 
-Initialize configuration files in current directory.
+Initialize configuration in current directory.
 
 ```bash
 ttt init                           # Interactive mode
 ttt init --user alice@example.com  # Pre-select user
 ttt init --label Frontend          # Set default label
 ttt init --force                   # Overwrite existing config
-ttt init -y                        # Non-interactive mode
 ```
 
 ### `ttt sync`
@@ -58,7 +67,8 @@ Sync current cycle issues from Linear.
 
 ```bash
 ttt sync              # Sync all matching issues
-ttt sync MP-123       # Sync only this specific issue
+ttt sync MP-123       # Sync specific issue only
+ttt sync --update     # Push local status changes to Linear (for local mode)
 ```
 
 ### `ttt work-on`
@@ -90,11 +100,9 @@ ttt status              # Show current in-progress task
 ttt status MP-123       # Show specific issue status
 ttt status MP-123 --set +1      # Move to next status
 ttt status MP-123 --set done    # Mark as done
-ttt status --set pending        # Reset current task
+ttt status MP-123 --set blocked # Set as blocked (waiting on dependency)
 ```
 
-Status options: `+1`, `-1`, `+2`, `-2`, `pending`, `in-progress`, `completed`, `blocked`, `todo`, `done`, `testing`
-
 ### `ttt config`
 
 Configure settings.
@@ -110,130 +118,21 @@ ttt config teams        # Configure multi-team selection
 
 ### Directory Structure
 
-After `ttt init`, your project will have:
-
 ```
 your-project/
-└── .ttt/                  # Config directory
-    ├── config.toon        # Team configuration (gitignore recommended)
-    ├── local.toon         # Personal settings (gitignore)
-    └── cycle.toon         # Current cycle data (gitignore, auto-generated)
-```
-
-### Custom Config Directory
-
-```bash
-# Use -d flag
-ttt sync -d ./team
-
-# Or set environment variable
-export TOON_DIR=./team
-ttt sync
+└── .ttt/
+    ├── config.toon     # Team config (gitignore recommended)
+    ├── local.toon      # Personal settings (gitignore)
+    ├── cycle.toon      # Current cycle data (auto-generated)
+    └── output/         # Downloaded attachments (images, files)
 ```
 
-### config.toon
-
-Team-wide configuration (fetched from Linear):
-
-```toon
-teams:
-  main:
-    id: TEAM_UUID
-    name: Team Name
-
-users:
-  alice:
-    id: USER_UUID
-    email: alice@example.com
-    displayName: Alice
-
-labels:
-  frontend:
-    id: LABEL_UUID
-    name: Frontend
-
-current_cycle:
-  id: CYCLE_UUID
-  name: Cycle #1
-```
-
-### local.toon
-
-Personal settings:
-
-```toon
-current_user: alice
-team: frontend
-teams[2]:
-  - frontend
-  - backend
-label: Frontend
-exclude_labels[1]:
-  - Bug
-exclude_assignees[1]:
-  - bob
-```
-
-| Field | Description |
-|-------|-------------|
-| `current_user` | Your user key from config.toon |
-| `team` | Primary team key |
-| `teams` | Multiple teams to sync (optional) |
-| `label` | Filter issues by label (optional) |
-| `exclude_labels` | Exclude issues with these labels (optional) |
-| `exclude_assignees` | Hide issues from these users (optional) |
-
-### config.toon - Status Mappings
-
-Configure which Linear statuses map to local states:
-
-```toon
-status_transitions:
-  todo: Todo
-  in_progress: In Progress
-  done: Done
-  testing: Testing
-```
-
-Run `ttt config status` to configure interactively.
-
-## Environment Variables
+### Environment Variables
 
 | Variable | Description |
 |----------|-------------|
 | `LINEAR_API_KEY` | **Required.** Your Linear API key |
-| `TOON_DIR` | Config directory (default: current directory) |
-
-## Integration Examples
-
-### With Claude Code
-
-```yaml
-# .claude/commands/sync.md
----
-description: Sync Linear issues
----
-ttt sync -d team
-```
-
-### As Git Submodule
-
-```bash
-# Add config directory as submodule
-git submodule add https://github.com/your-org/team-config.git team
-cd team && ttt sync
-```
-
-### In package.json
-
-```json
-{
-  "scripts": {
-    "sync": "ttt sync -d team",
-    "work": "ttt work-on -d team"
-  }
-}
-```
+| `TOON_DIR` | Config directory (default: `.ttt`) |
 
 ## License