From 9683418f9bf4d674bd147bbd7019b0c1189f10a4 Mon Sep 17 00:00:00 2001 From: Bruno Bornsztein Date: Thu, 19 Feb 2026 14:32:13 -0600 Subject: [PATCH] Add publishable TaskYou skill for Claude Code adoption - Rewrite SKILL.md to guide installation when ty is not present, removing the non-standard `requires` metadata that blocked loading - Add .claude-plugin/plugin.json for plugin marketplace distribution - Update install-skill.sh to support remote download (curl | bash) in addition to local symlink mode - Update orchestrator docs with all installation methods Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/plugin.json | 11 +++ docs/orchestrator.md | 28 +++++- scripts/install-skill.sh | 78 +++++++++------ skills/taskyou/SKILL.md | 188 ++++++++++++++++--------------------- 4 files changed, 165 insertions(+), 140 deletions(-) create mode 100644 .claude-plugin/plugin.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 00000000..338dc97f --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "taskyou", + "description": "Install and manage TaskYou — a personal task management system with Kanban board, background AI execution, and git worktree isolation.", + "version": "1.0.0", + "author": { + "name": "bborn" + }, + "homepage": "https://github.com/bborn/taskyou", + "repository": "https://github.com/bborn/taskyou", + "license": "MIT" +} diff --git a/docs/orchestrator.md b/docs/orchestrator.md index e91a871b..560e6f37 100644 --- a/docs/orchestrator.md +++ b/docs/orchestrator.md @@ -4,19 +4,37 @@ Task You's Kanban UI is great for humans, but every action it performs is also a ## Using the Claude Code Skill -Task You includes a `/taskyou` skill that teaches Claude Code (or any compatible agent) how to manage your task queue via CLI. +TaskYou includes a `/taskyou` skill that teaches Claude Code (or any compatible agent) how to install and manage your task queue via CLI. -**Automatic availability:** When working inside the Task You project, the skill is automatically loaded from `skills/taskyou/`. +### Installation Methods -**Global installation:** To use the skill from any project, run: +**1. Quick install (recommended — no repo needed):** + +```bash +curl -fsSL raw.githubusercontent.com/bborn/taskyou/main/scripts/install-skill.sh | bash +``` + +This downloads the skill to `~/.claude/skills/taskyou/` so you can use `/taskyou` from any project. + +**2. Plugin install (via Claude Code):** + +``` +/plugin install taskyou@bborn-taskyou +``` + +**3. From within the repo:** ```bash ./scripts/install-skill.sh ``` -This symlinks the skill to `~/.claude/skills/taskyou/` for personal access across all projects. +This symlinks the skill from the repo to `~/.claude/skills/taskyou/`. + +**4. Automatic:** When working inside the TaskYou project, the skill is automatically loaded from `skills/taskyou/`. + +### What It Does -Once available, you can say things like: +The skill guides installation of the `ty` CLI if not present, then provides full orchestration capabilities. Once available, you can say things like: - "Show me my task board" - "Execute the top priority task" diff --git a/scripts/install-skill.sh b/scripts/install-skill.sh index 11fe2665..cb50d649 100755 --- a/scripts/install-skill.sh +++ b/scripts/install-skill.sh @@ -1,18 +1,18 @@ #!/bin/bash -# Install the Task You skill for Claude Code (personal/global installation) +# Install the TaskYou skill for Claude Code # -# The skill is already available when working inside the Task You project -# (at skills/taskyou/SKILL.md). This script installs it globally -# so you can use /taskyou from any project. +# Two modes: +# 1. Local: Run from within the TaskYou repo to symlink the skill globally +# 2. Remote: Download the skill directly from GitHub (no repo needed) # # Usage: -# ./scripts/install-skill.sh +# From repo: ./scripts/install-skill.sh +# Remote: curl -fsSL raw.githubusercontent.com/bborn/taskyou/main/scripts/install-skill.sh | bash set -e -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_DIR="$(dirname "$SCRIPT_DIR")" -SKILL_SOURCE="$PROJECT_DIR/skills/taskyou" +REPO="bborn/taskyou" +BRANCH="main" SKILL_TARGET="$HOME/.claude/skills/taskyou" # Colors for output @@ -22,38 +22,62 @@ YELLOW='\033[1;33m' BLUE='\033[0;34m' NC='\033[0m' # No Color -echo "Installing Task You skill for Claude Code..." +info() { echo -e "${GREEN}==>${NC} $1"; } +warn() { echo -e "${YELLOW}Warning:${NC} $1"; } +error() { echo -e "${RED}Error:${NC} $1" >&2; exit 1; } -# Check if skill source exists -if [ ! -d "$SKILL_SOURCE" ]; then - echo -e "${RED}Error: Skill source not found at $SKILL_SOURCE${NC}" - exit 1 -fi +echo "" +echo " TaskYou Skill Installer" +echo " ========================" +echo "" -# Create skills directory if it doesn't exist +# Create skills directory mkdir -p "$HOME/.claude/skills" -# Remove existing symlink or directory +# Remove existing if [ -L "$SKILL_TARGET" ]; then - echo -e "${YELLOW}Removing existing symlink...${NC}" rm "$SKILL_TARGET" elif [ -d "$SKILL_TARGET" ]; then - echo -e "${YELLOW}Removing existing directory...${NC}" rm -rf "$SKILL_TARGET" fi -# Create symlink -ln -s "$SKILL_SOURCE" "$SKILL_TARGET" +# Check if running from within the repo +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}" 2>/dev/null)" && pwd 2>/dev/null)" || SCRIPT_DIR="" +PROJECT_DIR="$(dirname "$SCRIPT_DIR" 2>/dev/null)" || PROJECT_DIR="" +SKILL_SOURCE="$PROJECT_DIR/skills/taskyou" + +if [ -n "$SCRIPT_DIR" ] && [ -f "$SKILL_SOURCE/SKILL.md" ]; then + # Local mode: symlink from the repo + info "Installing from local repo..." + ln -s "$SKILL_SOURCE" "$SKILL_TARGET" + info "Symlinked $SKILL_TARGET -> $SKILL_SOURCE" +else + # Remote mode: download from GitHub + info "Downloading skill from GitHub..." + mkdir -p "$SKILL_TARGET" + + SKILL_URL="https://raw.githubusercontent.com/${REPO}/${BRANCH}/skills/taskyou/SKILL.md" + if ! curl -fsSL "$SKILL_URL" -o "$SKILL_TARGET/SKILL.md"; then + rm -rf "$SKILL_TARGET" + error "Failed to download skill from $SKILL_URL" + fi + + info "Downloaded to $SKILL_TARGET/SKILL.md" +fi -echo -e "${GREEN}Success!${NC} Task You skill installed globally." +echo "" +echo -e "${GREEN}Success!${NC} TaskYou skill installed for Claude Code." echo "" echo -e "${BLUE}Usage:${NC}" echo " Type /taskyou in Claude Code to invoke the skill" -echo " Or ask Claude to 'manage my task queue' and it will use the skill automatically" +echo " Or ask Claude to 'manage my task queue' — it will use the skill automatically" echo "" -echo -e "${BLUE}CLI commands:${NC}" -echo " Use 'ty' or 'taskyou' to interact with Task You from the command line" + +# Check if ty is installed +if command -v ty &>/dev/null; then + echo -e "${BLUE}TaskYou CLI:${NC} $(ty --version 2>/dev/null || echo 'installed')" +else + echo -e "${YELLOW}TaskYou CLI not found.${NC} The skill will guide installation when invoked." + echo " Or install now: curl -fsSL taskyou.dev/install.sh | bash" +fi echo "" -echo -e "${BLUE}Note:${NC}" -echo " The skill is also available automatically when working inside the Task You project." -echo " This global install lets you use /taskyou from any directory." diff --git a/skills/taskyou/SKILL.md b/skills/taskyou/SKILL.md index cd5e2be2..d0358691 100644 --- a/skills/taskyou/SKILL.md +++ b/skills/taskyou/SKILL.md @@ -1,19 +1,60 @@ --- name: taskyou -description: "Orchestrate Task You from any AI agent via CLI. Manage tasks, view the Kanban board, execute work, and track progress without touching the TUI." +description: "Install and manage TaskYou — a personal task management system with Kanban board, background AI execution, and git worktree isolation. Guides installation if not present, then orchestrates tasks via CLI." homepage: https://github.com/bborn/taskyou -metadata: {"requires":{"anyBins":["ty","taskyou"]}} --- -# Task You Orchestrator +# TaskYou — Install & Manage -You are an autonomous orchestrator for **Task You**, a personal task management system with a Kanban board, background execution, and git worktree isolation. +You are an autonomous orchestrator for **TaskYou**, a personal task management system with a Kanban board, background AI execution, and git worktree isolation. -**Your role:** Drive Task You via CLI commands to manage the task queue, execute work, and report progress. The user can always jump into the TUI (`ty` or `taskyou`) when they need direct control. +## First: Check Installation -**CLI commands:** Use `ty` (short) or `taskyou` (full) - both work identically. +Before running any commands, verify TaskYou is installed: -## Quick Reference +```bash +which ty || echo "NOT_INSTALLED" +``` + +### If NOT installed, guide the user through installation: + +**Quick install (recommended):** + +```bash +curl -fsSL taskyou.dev/install.sh | bash +``` + +This auto-detects OS/arch (macOS and Linux, amd64 and arm64) and installs `ty` to `~/.local/bin/`. + +**Options:** +- `--no-ssh-server` — Skip installing taskd (the SSH daemon for remote access) +- Set `INSTALL_DIR=/custom/path` to change install location + +**After install, verify:** + +```bash +ty --version +``` + +If `~/.local/bin` is not in PATH, tell the user to add it: + +```bash +export PATH="$HOME/.local/bin:$PATH" +``` + +**Upgrading an existing install:** + +```bash +ty upgrade +``` + +### If already installed, proceed to task management below. + +--- + +## CLI Reference + +Use `ty` (short) or `taskyou` (full) — both work identically. | Action | Command | |--------|---------| @@ -27,7 +68,6 @@ You are an autonomous orchestrator for **Task You**, a personal task management | Pin/prioritize | `ty pin ` | | Close/complete | `ty close ` | | Delete | `ty delete ` | -| **Executor interaction** | | | See executor output | `ty output ` | | Send input to executor | `ty input "message"` | | Confirm prompt | `ty input --enter` | @@ -77,7 +117,7 @@ Then retry with feedback: ty retry --feedback "Here's the clarification you need..." ``` -### 3b. Direct Executor Interaction +### 4. Direct Executor Interaction For running/blocked tasks, you can interact directly with the executor: @@ -97,18 +137,18 @@ This is useful when: - You need to respond to a TUI prompt (use `--key` for navigation) - You want to see what's happening without attaching to tmux -### 4. Create New Tasks +### 5. Create New Tasks ```bash ty create "Implement feature X" --body "Detailed description here..." ``` Optional flags: -- `--project ` - Associate with a project -- `--type ` - Task type (bug, feature, etc.) -- `--dangerous` - Skip permission prompts in executor +- `--project ` — Associate with a project +- `--type ` — Task type (bug, feature, etc.) +- `--dangerous` — Skip permission prompts in executor -### 5. Manage Priority +### 6. Manage Priority Pin important tasks to the top: @@ -118,7 +158,7 @@ ty pin --unpin # Unpin ty pin --toggle # Toggle ``` -### 6. Change Status Manually +### 7. Change Status Move tasks between columns: @@ -128,14 +168,14 @@ ty status queued # Queue for execution ty status done # Mark complete ``` -### 7. Close and Cleanup +### 8. Close and Cleanup ```bash ty close # Mark as done ty delete # Permanently remove ``` -## JSON Output for Automation +## JSON Output All commands support `--json` for machine-readable output: @@ -154,38 +194,23 @@ ty list --json | jq '.[] | select(.pinned == true)' # Pinned tasks only ## Orchestration Patterns -### Continuous Monitoring Loop - -```bash -while true; do - ty board --json | jq -r '.columns.blocked.tasks[].id' | while read id; do - echo "Task $id is blocked - needs attention" - done - sleep 30 -done -``` - ### Auto-Execute Queued Tasks ```bash ty list --status queued --json | jq -r '.[0].id' | xargs -I{} ty execute {} ``` -### Batch Status Updates +### Continuous Monitoring ```bash -ty list --status backlog --json | jq -r '.[].id' | xargs -n1 ty status {} queued +while true; do + ty board --json | jq -r '.columns.blocked.tasks[].id' | while read id; do + echo "Task $id is blocked - needs attention" + done + sleep 30 +done ``` -## Best Practices - -1. **Always check the board first** - Understand context before acting -2. **Use JSON output** - Structured data is easier to process and reason about -3. **Provide meaningful feedback** - When retrying blocked tasks, give clear context -4. **Monitor execution** - Use `ty show --logs` to track progress -5. **Respect priorities** - Check pinned tasks first -6. **Create focused tasks** - One clear objective per task works best - ## Task Lifecycle ``` @@ -199,55 +224,39 @@ backlog → queued → processing → done - **blocked**: Waiting for user input/clarification - **done**: Completed successfully -## Integration Tips - -### With External Schedulers - -Task You doesn't have built-in recurring tasks. Use cron or external schedulers: +## MCP Tools (When Running Inside TaskYou) -```bash -# Run daily standup at 9am -0 9 * * * ty create "Daily standup review" && ty execute $(ty list --status backlog --json | jq -r '.[0].id') -``` +If you're running as the task executor inside a TaskYou worktree, you have access to MCP tools: -### With Other AI Agents +- `taskyou_complete` — Mark your task complete +- `taskyou_needs_input` — Request user input (blocks task) +- `taskyou_show_task` — Get your task details +- `taskyou_create_task` — Create follow-up tasks +- `taskyou_list_tasks` — See other active tasks +- `taskyou_spotlight` — Sync worktree changes to main repo for testing -This skill works with any agent that can execute shell commands: -- **Claude Code**: Native integration via hooks -- **Codex**: Use `codex exec "ty board --json && ..."` -- **Gemini**: Use `gemini code "Run ty board --json and summarize"` -- **OpenCode/Pi**: Same pattern - shell out to `ty` CLI +Use these instead of CLI when executing inside a TaskYou worktree. -### Dashboard Mode - -For a rolling view of the board: +## Best Practices -```bash -watch -n30 "ty board" -``` +1. **Always check the board first** — Understand context before acting +2. **Use JSON output** — Structured data is easier to process and reason about +3. **Provide meaningful feedback** — When retrying blocked tasks, give clear context +4. **Monitor execution** — Use `ty show --logs` to track progress +5. **Respect priorities** — Check pinned tasks first +6. **Create focused tasks** — One clear objective per task works best ## Troubleshooting ### Task stuck in processing? -Check if the executor is running and what it's doing: ```bash ty show --logs ty output # See live terminal output ``` -### Executor waiting for input? - -Check the output and respond directly: -```bash -ty output # See what it's asking -ty input --enter # Confirm a prompt -ty input "yes" # Send specific input -``` - ### No tasks executing? -Ensure the daemon is running: ```bash ty daemon status ty daemon restart # If needed @@ -255,43 +264,6 @@ ty daemon restart # If needed ### Can't find a task? -Search by status: ```bash ty list --status done --json | jq '.[] | select(.title | contains("keyword"))' ``` - -## MCP Tools (When Running Inside Task You) - -If you're running as the task executor, you have access to MCP tools: - -- `taskyou_complete` - Mark your task complete -- `taskyou_needs_input` - Request user input (blocks task) -- `taskyou_show_task` - Get your task details -- `taskyou_create_task` - Create follow-up tasks -- `taskyou_list_tasks` - See other active tasks -- `taskyou_spotlight` - Sync worktree changes to main repo for testing - -Use these instead of CLI when executing inside a Task You worktree. - -### Spotlight Mode - -Spotlight mode bridges the gap between isolated worktree development and testing in the main repository. It syncs your worktree changes back to the main repo so you can run and test your app there. - -``` -# Enable spotlight (syncs changes to main repo) -taskyou_spotlight(action="start") - -# Manually sync after more changes -taskyou_spotlight(action="sync") - -# Check status -taskyou_spotlight(action="status") - -# Disable and restore main repo to original state -taskyou_spotlight(action="stop") -``` - -Use this when: -- Your app has directory-dependent assumptions (needs to run from repo root) -- You need to test with resources already configured in the main repo (databases, ports) -- Your project has fast incremental rebuilds but slow initial builds