@masslessai/push-todo 3.4.5 → 3.4.6

package/SKILL.md

@@ -1,180 +1,197 @@
-# Push Todo Skill
+---
+description: Show active voice tasks from Push iOS app
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+---
 
-This skill enables Claude Code to fetch and work on voice tasks captured via the Push iOS app.
+# Push Voice Tasks
 
-## Quick Start
+This command fetches and displays your active voice tasks from the Push iOS app.
 
-1. Run `push-todo connect` to authenticate
-2. Run `push-todo` to list active tasks
-3. Run `push-todo <number>` to view and work on a specific task
+## Usage
 
-## Commands
+- `/push-todo` - Show active tasks for current project
+- `/push-todo #427` - Jump directly to task #427
+- `/push-todo review` - Review existing tasks and mark completed ones
+- `/push-todo setup` - Configure your Push connection
 
-### List Tasks
+> **Note:** To see tasks from all projects, ask explicitly: "show tasks from all projects"
 
-```bash
-push-todo                    # Active tasks for current project
-push-todo --all-projects     # Tasks from all projects
-push-todo --backlog          # Backlog items only
-push-todo --include-backlog  # Active + backlog
-push-todo --completed        # Completed items only
-push-todo --json             # Output as JSON
-```
+## Instructions
 
-### View Specific Task
+When this command is invoked:
 
-```bash
-push-todo 427                # View task #427
-push-todo 427 --json         # As JSON
-```
+1. **Check for setup**: First verify the config exists:
+   ```bash
+   test -f ~/.config/push/config && echo "configured" || echo "not configured"
+   ```
 
-### Search Tasks
+2. **If not configured**: Run the setup flow (see [Setup Mode](#setup-mode) below)
 
-```bash
-push-todo search "auth bug"  # Search for tasks
-push-todo --search "fix"     # Alternative syntax
-```
+3. **If configured**: Fetch tasks:
+   ```bash
+   push-todo
+   ```
 
-### Manage Tasks
+4. Present the tasks and ask which one to work on
 
-```bash
-push-todo --queue 427,428    # Queue tasks for daemon
-push-todo --queue-batch      # Auto-queue a batch
-push-todo --mark-completed <uuid> --completion-comment "Fixed the bug"
-```
+5. When user selects a task, mark it as started and begin working
 
-### Connection & Status
+## Review Mode
 
-```bash
-push-todo connect            # Run diagnostics, authenticate
-push-todo status             # Show connection status
-push-todo setting            # Show all settings
-push-todo setting auto-commit # Toggle a setting
-```
+When `/push-todo review` is invoked, use **session context** to identify completed tasks:
+
+### Step 1: Analyze Session Context
+
+First, recall what was worked on in this session (or the previous compacted session):
+- What tasks were explicitly mentioned? (e.g., "work on #701")
+- What features were implemented or bugs fixed?
+- What files were edited and why?
 
-### Monitor
+### Step 2: Fetch Pending Tasks
 
 ```bash
-push-todo --watch            # Live terminal UI
-push-todo --watch --json     # JSON status output
+push-todo --all-projects --json
 ```
 
-## Task Format
+### Step 3: Match Session Work Against Tasks
 
-Tasks include:
+For each pending task, check if it matches work done in this session:
 
-- **summary**: Brief title
-- **content/normalizedContent**: Full task description (AI-extracted)
-- **originalTranscript**: Raw voice recording text
-- **displayNumber**: Human-readable number (#1, #2...)
-- **projectHint**: Associated project (git remote)
-- **screenshotAttachments**: Any attached screenshots
-- **linkAttachments**: Any attached links
+**Explicit Match**: Task number was mentioned (e.g., "worked on #701")
+- These should be marked complete unless work is clearly unfinished
 
-## Batch Processing
+**Implicit Match**: Work done aligns with task content semantically
+- Compare task summary/content against session work
+- Example: Task says "add review parameter to slash command" and we just added that feature
 
-The CLI supports batch task processing:
+**No Match**: Task wasn't worked on this session
+- Skip these (don't search codebase unnecessarily)
 
-1. Fetch multiple tasks with `push-todo`
-2. Tasks marked for batch will show `BATCH_OFFER` format
-3. Use `--queue` to add tasks to the daemon queue
+### Step 4: Present Findings
 
-## Integration with Claude Code
+```
+## Session Review
+
+Based on this session, I found:
 
-### Session Start Hook
+### Completed This Session
+- #701 "Add review parameter" - We implemented this feature (explicit)
+- #427 "Fix login bug" - We fixed the auth issue in LoginView.swift (implicit match)
 
-When Claude Code starts, the hook shows:
+### Not Worked On
+- #351 "Test on smaller phone" - No related work this session
+- #682 "Rework recording overlay" - No related work this session
+
+Should I mark #701 and #427 as completed?
 ```
-[Push] You have 5 active tasks from your iPhone. Say 'push-todo' to see them.
+
+### Step 5: Mark Confirmed Tasks
+
+```bash
+push-todo --mark-completed TASK_UUID --completion-comment "Completed in Claude Code session"
 ```
 
-### Session End Hook
+### Key Principle
 
-Reports session completion to the Push backend.
+**Session context is primary** - don't grep the entire codebase for every task. Use conversation history to identify what was actually worked on, then match against tasks semantically. This catches both:
+- Explicit: User said "work on #701" but forgot to mark complete
+- Implicit: User fixed something that matches a task they didn't mention
 
-### Slash Command
+## Setup Mode
 
-Use `/push-todo` in Claude Code as a shortcut:
-- `/push-todo` - List tasks
-- `/push-todo 427` - Work on task #427
-- `/push-todo connect` - Run diagnostics
+When `/push-todo setup` is invoked, generate project-specific keywords BEFORE running the setup script.
 
-## Settings
+### Why Keywords Matter
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `AUTO_COMMIT` | `true` | Auto-commit changes after task completion |
-| `MAX_BATCH_SIZE` | `5` | Maximum tasks in batch offer |
+Keywords help the AI route voice todos to the correct project. Generic keywords like "coding" or "programming" don't differentiate between projects. We need UNIQUE keywords that identify THIS specific project.
 
-Toggle with: `push-todo setting auto-commit`
+### Step 1: Understand the Project
 
-## Project Registration
+Read the project context to generate meaningful keywords:
 
-Projects are identified by their git remote URL. Register with:
+1. **Check for CLAUDE.md**:
+   ```bash
+   test -f CLAUDE.md && echo "found" || echo "not found"
+   ```
 
-```bash
-push-todo connect
-```
+2. **If CLAUDE.md exists**, read the header section:
+   ```bash
+   head -80 CLAUDE.md
+   ```
 
-This maps the git remote to the local path, enabling:
-- Automatic project filtering
-- Daemon task routing
-- Cross-machine synchronization
+3. **If no CLAUDE.md**, check for README.md:
+   ```bash
+   test -f README.md && head -50 README.md
+   ```
 
-## E2EE (End-to-End Encryption)
+### Step 2: Generate Unique Keywords
 
-If enabled on the Push app:
-- Tasks are encrypted on device
-- Decryption uses iCloud Keychain
-- Requires macOS with keychain access
+Based on the project context, generate 5-10 keywords.
 
-Check status: `push-todo status`
+**MUST include:**
+- Project name and common nicknames users would say
+- Domain-specific terms (e.g., "voice todo" for a voice app)
+- Distinctive tech if relevant (e.g., "whisper" for speech recognition)
 
-## Configuration
+**MUST NOT include (these are useless for differentiation):**
+- Generic terms: "coding", "programming", "development"
+- Tool terms: "mac", "terminal", "cli", "ai", "task"
+- Any term that applies to ALL code projects
 
-Config file: `~/.config/push/config`
+**Think:** "What would the user SAY when creating a task for THIS project?"
+
+### Step 3: Generate Description
+
+Generate a short (5-15 words) description that captures what makes this project unique. NOT generic like "coding tasks" or "development work".
+
+### Step 4: Run Setup with Keywords
 
 ```bash
-export PUSH_KEY="your-api-key"
-export PUSH_USER_ID="user-uuid"
-export AUTO_COMMIT="true"
-export MAX_BATCH_SIZE="5"
+push-todo connect --keywords "keyword1,keyword2,keyword3,..." --description "Short unique description"
 ```
 
-## Troubleshooting
+### Examples
 
-### "No API key configured"
-Run `push-todo connect` to authenticate.
+**For a voice todo app (Push):**
+```bash
+push-todo connect --keywords "push,voice,todo,whisper,ios,swiftui,recording,speech,transcription" --description "Voice-powered todo app for iOS with whisper speech recognition"
+```
 
-### "E2EE not available"
-The keychain helper binary may not be installed. Check:
-- macOS only (not Linux/Windows)
-- Binary at `node_modules/@masslessai/push-todo/bin/push-keychain-helper`
+**For a web scraping project:**
+```bash
+push-todo connect --keywords "scraper,crawler,beautifulsoup,selenium,extraction,parsing" --description "Web scraping tool for data extraction"
+```
 
-### "Invalid API key"
-Your key may have expired. Run `push-todo connect` to re-authenticate.
+**For a game engine:**
+```bash
+push-todo connect --keywords "engine,graphics,rendering,physics,ecs,vulkan,gamedev" --description "Custom game engine with Vulkan renderer"
+```
 
-### Tasks not showing for project
-Run `push-todo connect` to register the current project, or use `--all-projects`.
+### Fallback (No Documentation)
 
-## API Reference
+If no CLAUDE.md or README.md exists, generate minimal keywords from:
+- Folder name
+- Git repo name
+- Primary file extensions (`.swift` -> iOS, `.py` -> Python, `.rs` -> Rust)
 
-The CLI also exports a programmatic API:
+## CLI Reference
 
-```javascript
-import {
-  listTasks,
-  showTask,
-  searchTasks,
-  markComplete
-} from '@masslessai/push-todo';
+The `push-todo` CLI supports these commands:
 
-// List tasks
-const tasks = await listTasks({ allProjects: true });
+| Command | Description |
+|---------|-------------|
+| `push-todo` | List active tasks for current project |
+| `push-todo <number>` | Show specific task (e.g., `push-todo 427`) |
+| `push-todo --all-projects` | List tasks from all projects |
+| `push-todo --backlog` | Show backlog items |
+| `push-todo connect` | Run connection diagnostics and setup |
+| `push-todo search <query>` | Search tasks |
+| `push-todo --status` | Show connection status |
+| `push-todo --mark-completed <uuid>` | Mark task as completed |
+| `push-todo --json` | Output as JSON |
 
-// Search
-const results = await searchTasks('bug fix');
+## What is Push?
 
-// Mark complete
-await markComplete(taskId, 'Fixed the issue');
-```
+Push is a voice-powered todo app for iOS. Users capture tasks by speaking on their phone, and those tasks sync to Claude Code for implementation.
+
+Learn more: https://pushto.do

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masslessai/push-todo",
-  "version": "3.4.5",
+  "version": "3.4.6",
   "description": "Voice tasks from Push iOS app for Claude Code",
   "type": "module",
   "bin": {
@@ -17,10 +17,8 @@
     "bin/",
     "lib/",
     "hooks/",
-    "commands/",
     "natives/",
     "scripts/",
-    ".claude-plugin/",
     "SKILL.md",
     "LICENSE"
   ],
@@ -35,7 +33,7 @@
   },
   "keywords": [
     "claude-code",
-    "claude-code-plugin",
+    "claude-code-skill",
     "push",
     "voice",
     "todo",

package/scripts/postinstall.js

@@ -3,7 +3,7 @@
  * Post-install script for Push CLI.
  *
  * Sets up integrations for ALL detected AI coding clients:
- * 1. Claude Code - symlink to ~/.claude/plugins/
+ * 1. Claude Code - symlink to ~/.claude/skills/ (gives clean /push-todo command)
  * 2. OpenAI Codex - AGENTS.md in ~/.codex/
  * 3. Clawdbot - SKILL.md in ~/.clawdbot/skills/
  * 4. Downloads native keychain helper binary (macOS)
@@ -24,10 +24,10 @@ const PACKAGE_ROOT = join(__dirname, '..');
 
 // Claude Code locations
 const CLAUDE_DIR = join(homedir(), '.claude');
-const PLUGIN_DIR = join(CLAUDE_DIR, 'plugins');
-const PLUGIN_LINK = join(PLUGIN_DIR, 'push-todo');
-const LEGACY_SKILL_DIR = join(CLAUDE_DIR, 'skills');
-const LEGACY_SKILL_LINK = join(LEGACY_SKILL_DIR, 'push-todo');
+const SKILL_DIR = join(CLAUDE_DIR, 'skills');
+const SKILL_LINK = join(SKILL_DIR, 'push-todo');
+const LEGACY_PLUGIN_DIR = join(CLAUDE_DIR, 'plugins');
+const LEGACY_PLUGIN_LINK = join(LEGACY_PLUGIN_DIR, 'push-todo');
 
 // OpenAI Codex locations
 const CODEX_DIR = join(homedir(), '.codex');
@@ -51,81 +51,84 @@ const BINARY_URL = `https://github.com/MasslessAI/push-todo-cli/releases/downloa
 const BINARY_URL_X64 = `https://github.com/MasslessAI/push-todo-cli/releases/download/v${VERSION}/${BINARY_NAME}-darwin-x64`;
 
 /**
- * Set up Claude Code plugin by creating symlink.
+ * Set up Claude Code skill by creating symlink.
  *
- * Creates: ~/.claude/plugins/push-todo -> <npm-package-location>
+ * Creates: ~/.claude/skills/push-todo -> <npm-package-location>
+ *
+ * Skills give clean slash commands like /push-todo (no namespace prefix).
  *
  * @returns {boolean} True if successful
  */
-function setupClaudePlugin() {
+function setupClaudeSkill() {
   try {
-    // Ensure ~/.claude/plugins/ directory exists
-    if (!existsSync(PLUGIN_DIR)) {
-      mkdirSync(PLUGIN_DIR, { recursive: true });
-      console.log('[push-todo] Created ~/.claude/plugins/ directory');
+    // Ensure ~/.claude/skills/ directory exists
+    if (!existsSync(SKILL_DIR)) {
+      mkdirSync(SKILL_DIR, { recursive: true });
+      console.log('[push-todo] Created ~/.claude/skills/ directory');
     }
 
     // Check if symlink already exists
-    if (existsSync(PLUGIN_LINK)) {
+    if (existsSync(SKILL_LINK)) {
       try {
-        const stats = lstatSync(PLUGIN_LINK);
+        const stats = lstatSync(SKILL_LINK);
         if (stats.isSymbolicLink()) {
-          const currentTarget = readlinkSync(PLUGIN_LINK);
+          const currentTarget = readlinkSync(SKILL_LINK);
           if (currentTarget === PACKAGE_ROOT) {
-            console.log('[push-todo] Claude Code plugin symlink already configured.');
+            console.log('[push-todo] Claude Code skill symlink already configured.');
             return true;
           }
           // Different target - remove and recreate
           console.log('[push-todo] Updating existing symlink...');
-          unlinkSync(PLUGIN_LINK);
+          unlinkSync(SKILL_LINK);
         } else {
           // It's a directory or file, not a symlink - back it up
-          console.log('[push-todo] Found existing plugin directory, backing up...');
-          const backupPath = `${PLUGIN_LINK}.backup.${Date.now()}`;
-          rmSync(PLUGIN_LINK, { recursive: true });
+          console.log('[push-todo] Found existing skill directory, backing up...');
+          const backupPath = `${SKILL_LINK}.backup.${Date.now()}`;
+          rmSync(SKILL_LINK, { recursive: true });
           console.log(`[push-todo] Backed up to ${backupPath}`);
         }
       } catch (err) {
-        console.log(`[push-todo] Warning: Could not check existing plugin: ${err.message}`);
+        console.log(`[push-todo] Warning: Could not check existing skill: ${err.message}`);
       }
     }
 
     // Create the symlink
-    symlinkSync(PACKAGE_ROOT, PLUGIN_LINK);
-    console.log('[push-todo] Claude Code plugin installed:');
-    console.log(`[push-todo]   ~/.claude/plugins/push-todo -> ${PACKAGE_ROOT}`);
+    symlinkSync(PACKAGE_ROOT, SKILL_LINK);
+    console.log('[push-todo] Claude Code skill installed:');
+    console.log(`[push-todo]   ~/.claude/skills/push-todo -> ${PACKAGE_ROOT}`);
     return true;
   } catch (error) {
-    console.error(`[push-todo] Failed to set up Claude Code plugin: ${error.message}`);
+    console.error(`[push-todo] Failed to set up Claude Code skill: ${error.message}`);
     console.log('[push-todo] You can manually create the symlink:');
-    console.log(`[push-todo]   ln -s "${PACKAGE_ROOT}" "${PLUGIN_LINK}"`);
+    console.log(`[push-todo]   ln -s "${PACKAGE_ROOT}" "${SKILL_LINK}"`);
     return false;
   }
 }
 
 /**
- * Clean up legacy installation (Python version in ~/.claude/skills/).
+ * Clean up legacy plugin installation (in ~/.claude/plugins/).
+ * We migrated from plugins to skills for cleaner /push-todo command.
  */
 function cleanupLegacyInstallation() {
-  if (!existsSync(LEGACY_SKILL_LINK)) {
+  if (!existsSync(LEGACY_PLUGIN_LINK)) {
     return;
   }
 
   try {
-    const stats = lstatSync(LEGACY_SKILL_LINK);
+    const stats = lstatSync(LEGACY_PLUGIN_LINK);
 
     if (stats.isSymbolicLink()) {
-      const target = readlinkSync(LEGACY_SKILL_LINK);
-      // Check if it points to old Python location
-      if (target.includes('plugins/push-todo') || target.includes('push-todo-cli')) {
-        console.log('[push-todo] Removing legacy symlink at ~/.claude/skills/push-todo');
-        unlinkSync(LEGACY_SKILL_LINK);
-        console.log('[push-todo] Legacy symlink removed.');
-      }
+      console.log('[push-todo] Removing legacy plugin symlink at ~/.claude/plugins/push-todo');
+      unlinkSync(LEGACY_PLUGIN_LINK);
+      console.log('[push-todo] Legacy plugin symlink removed.');
+    } else if (stats.isDirectory()) {
+      console.log('[push-todo] Removing legacy plugin directory at ~/.claude/plugins/push-todo');
+      rmSync(LEGACY_PLUGIN_LINK, { recursive: true });
+      console.log('[push-todo] Legacy plugin directory removed.');
     }
   } catch (error) {
     // Ignore errors - this is best-effort cleanup
-    console.log(`[push-todo] Note: Could not clean up legacy installation: ${error.message}`);
+    console.log(`[push-todo] Note: Could not clean up legacy plugin: ${error.message}`);
   }
 }
 
@@ -331,9 +334,9 @@ async function main() {
   // Step 2: Clean up legacy installation
   cleanupLegacyInstallation();
 
-  // Step 3: Set up Claude Code plugin symlink
-  console.log('[push-todo] Setting up Claude Code plugin...');
-  const claudeSuccess = setupClaudePlugin();
+  // Step 3: Set up Claude Code skill symlink
+  console.log('[push-todo] Setting up Claude Code skill...');
+  const claudeSuccess = setupClaudeSkill();
   console.log('');
 
   // Step 4: Set up OpenAI Codex (if installed)

package/.claude-plugin/plugin.json

@@ -1,5 +0,0 @@
-{
-  "name": "push-todo",
-  "version": "3.4.5",
-  "description": "Voice tasks from Push iOS app"
-}

package/commands/push-todo.md

@@ -1,78 +0,0 @@
-# Push Todo - Voice Tasks from iPhone
-
-Fetch and work on voice tasks captured via the Push iOS app.
-
-## How to Use
-
-Run `/push-todo` to see your active tasks, or `/push-todo <number>` to work on a specific task.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `/push-todo` | List all active tasks for current project |
-| `/push-todo <number>` | Work on specific task (e.g., `/push-todo 427`) |
-| `/push-todo --all-projects` | List tasks from all projects |
-| `/push-todo --backlog` | Show backlog items |
-| `/push-todo connect` | Run connection diagnostics |
-| `/push-todo search <query>` | Search tasks |
-| `/push-todo status` | Show connection status |
-
-## Task Output Format
-
-When you fetch a task, you'll see:
-
-```
-## Task: #427 Fix authentication bug
-
-**Project:** github.com/user/repo
-
-### Content
-Users are getting logged out randomly. Need to investigate the session token expiration logic.
-
-### Original Voice Transcript
-> "There's a bug where users get logged out randomly, I think it's the session token expiration"
-
-**Task ID:** `550e8400-e29b-41d4-a716-446655440000`
-**Display Number:** #427
-**Status:** Active
-**Created:** 2026-01-15T10:30:00Z
-```
-
-## Batch Offer Format
-
-When multiple tasks are available, you may see a batch offer:
-
-```
-==================================================
-BATCH_OFFER: 3
-BATCH_TASKS: 427,428,429
-  #427 - Fix authentication bug
-  #428 - Add dark mode support
-  #429 - Update API documentation
-==================================================
-```
-
-## Working on Tasks
-
-When you fetch a specific task:
-
-1. Read the **Content** section for the full task description
-2. Check the **Original Voice Transcript** for additional context
-3. Implement the requested changes
-4. Mark the task as completed when done
-
-## Completion
-
-After completing a task, the task will be marked as done and synced back to the Push app on your iPhone.
-
-## Project Context
-
-Tasks are associated with git repositories. The CLI automatically detects your current project and shows only relevant tasks.
-
-- Use `--all-projects` to see tasks from all registered projects
-- Run `push-todo connect` to register the current project
-
-## E2EE Support
-
-If you have End-to-End Encryption enabled on the Push app, the CLI will automatically decrypt task content using your iCloud Keychain.