Yatta! - Task & Capacity Management

用于任务和能力管理的个人生产力系统。创建和组织具有丰富属性（优先级、工作量、复杂性、标签）的任务，跟踪时间和连续情况，跨项目和上下文管理容量，查看艾森豪威尔矩阵优先级，同步日历订阅，处理委派和后续行动，并获得人工智能驱动的见解。支持批量操作、多项目工作流程和实时容量规划，防止过度使用。安全性：v0.2.0 消除了 v0.1.3 中的 RCE 漏洞（示例中的 shell/JSON 注入），添加了端点验证、安全 jq 模式。

## 概述（中文）

用于任务和能力管理的个人生产力系统。创建和组织具有丰富属性（优先级、工作量、复杂性、标签）的任务，跟踪时间和连续情况，跨项目和上下文管理容量，查看艾森豪威尔矩阵优先级，同步日历订阅，处理委派和后续行动，并获得人工智能驱动的见解。支持批量操作、多项目工作流程和实时容量规划，防止过度使用。安全性：v0.2.0 消除了 v0.1.3 中的 RCE 漏洞（示例中的 shell/JSON 注入），添加了端点验证、安全 jq 模式。

## 原文

# Yatta! Skill

Interact with Yatta! task management system via API. Requires an API key from your Yatta! account.

## ⚠️ Security Warning

**This skill can perform DESTRUCTIVE operations on your Yatta! account:**

- **Task Management:** Create, update, archive, and batch-modify tasks
- **Project Management:** Create, update, and archive projects
- **Context Management:** Create contexts and assign them to tasks
- **Comment Management:** Add, update, and delete task comments
- **Calendar Management:** Create, sync, and modify calendar subscriptions
- **Follow-Up Management:** Update delegation schedules and mark complete
- **Capacity Management:** Trigger capacity computations

**Operation Types:**

**Read-Only Operations** (✅ Safe):
- List tasks, projects, contexts, comments
- Get analytics, insights, streaks
- View capacity and calendar data
- Get Eisenhower Matrix view
- All GET requests

**Destructive Operations** (⚠️ Modify or delete data):
- Create/update/archive tasks (POST, PUT, DELETE)
- Batch update tasks
- Create/update projects
- Create/assign contexts
- Add/update/delete comments
- Add/sync calendar subscriptions
- Update follow-up schedules
- All POST, PUT, DELETE requests

**Best Practices:**
1. **Review commands before running** - Check what the API call will do
2. **No undo for deletions** - Archived tasks can be recovered, but some operations are permanent
3. **Test on non-critical data first** - Create test tasks/projects to verify behavior
4. **Batch operations affect multiple items** - Be extra careful with batch updates
5. **Real-time sync** - Changes appear in Yatta! UI immediately

For detailed API operation documentation, see [API-REFERENCE.md](API-REFERENCE.md).

## Setup

### ⚠️ API Key Security

**Your Yatta! API key provides FULL access to your account:**
- Can create, read, update, and delete ALL tasks, projects, contexts
- Can modify calendar subscriptions and follow-up schedules
- Can archive data and trigger computations
- **No read-only scopes available** - keys have full permissions

**Security Best Practices:**
- Store keys in a secure password manager (1Password CLI recommended)
- Use environment variables, never hardcode keys in scripts
- Rotate keys regularly (every 90 days recommended)
- Create separate keys for different integrations
- Revoke unused keys immediately
- **Never commit keys to version control**

### 1. Get Your API Key

1. Log into Yatta! app
2. Go to Settings → API Keys
3. Create new key (e.g., "OpenClaw Integration")
4. Copy the `yatta_...` key
5. Store it securely

### 2. Configure the Skill

**Option A: Environment Variables (Recommended)**
```bash
# Add to your shell profile (~/.zshrc, ~/.bashrc)
export YATTA_API_KEY="yatta_your_key_here"
export YATTA_API_URL="https://zunahvofybvxpptjkwxk.supabase.co/functions/v1"  # Default
```

**Option B: 1Password CLI (Most Secure)**
```bash
# Store key in 1Password
op item create --category=API_CREDENTIAL \
  --title="Yatta API Key" \
  api_key[password]="yatta_your_key_here"

# Use in commands
export YATTA_API_KEY=$(op read "op://Private/Yatta API Key/api_key")
```

### ⚠️ API Endpoint Verification

**The default API endpoint is hosted on Supabase:**

- **Default URL:** `https://zunahvofybvxpptjkwxk.supabase.co/functions/v1`
- **Project:** Yatta! production backend
- **Owner:** Chris Giddings (chris@chrisgiddings.net)
- **App:** https://yattadone.com

**Why Supabase?**
- Yatta! uses Supabase as its backend infrastructure
- The URL is a direct Supabase project endpoint
- Branded URL (api.yattadone.com) is on the roadmap

**Verification steps:**

1. **Verify app ownership:**
   - Visit https://yattadone.com
   - Check Settings → About or footer for API endpoint confirmation
   
2. **Check SSL certificate:**
   ```bash
   openssl s_client -connect zunahvofybvxpptjkwxk.supabase.co:443 \
     -servername zunahvofybvxpptjkwxk.supabase.co < /dev/null 2>&1 \
     | openssl x509 -noout -subject -issuer
   ```

3. **Run verification script:**
   ```bash
   # Automated endpoint verification
   bash scripts/verify-endpoint.sh
   ```

4. **Contact support if uncertain:**
   - Email: support@yattadone.com
   - Only send API keys to verified endpoints

**Branded URL (Coming Soon):**
- Future: `https://api.yattadone.com/v1`
- Current Supabase URL will continue to work
- Skill will auto-update default when branded URL is live

**Security note:**
Only send your API key to endpoints you trust and have verified.
If you prefer to wait for the branded API URL, that's a valid security choice.

### 3. Test Connection
   ```bash
   curl -s "$YATTA_API_URL/tasks" \
     -H "Authorization: Bearer $YATTA_API_KEY" \
     | jq '.[:3]'  # Show first 3 tasks
   ```

## 🔒 Security: Input Validation

**⚠️ CRITICAL: This skill is vulnerable to shell and JSON injection if user input is not properly sanitized.**

### Safe Coding Patterns (Required)

**ALL examples in this skill use safe patterns:**
- ✅ **JSON payloads:** Built with `jq -n --arg` (prevents JSON injection)
- ✅ **URL parameters:** Encoded with `jq -sRr @uri` (prevents shell injection)  
- ✅ **No direct string interpolation** in JSON or URLs

### Quick Reference

```bash
# ✅ SAFE: JSON construction
PAYLOAD=$(jq -n --arg title "$TITLE" '{title: $title}')
curl -d "$PAYLOAD" ...

# ✅ SAFE: URL encoding
TASK_ID_ENCODED=$(printf %s "$TASK_ID" | jq -sRr @uri)
curl "$API_URL/tasks/$TASK_ID_ENCODED" ...

# ✅ BEST: Use wrapper functions
source scripts/yatta-safe-api.sh
yatta_create_task "Finish report" "high"
```

### Why This Matters

**Unsafe patterns can lead to:**
- API key exfiltration
- Arbitrary command execution (RCE)
- Data manipulation and corruption

**See [SECURITY.md](SECURITY.md) for:**
- Detailed vulnerability examples
- Attack scenarios and impact
- Safe coding patterns
- Testing guidelines

**See [scripts/yatta-safe-api.sh](scripts/yatta-safe-api.sh) for:**
- Pre-built safe wrapper functions
- Ready-to-use examples
- Zero boilerplate

---

## 🎯 Invocation Policy

**This skill requires MANUAL invocation only.**

### Policy Details

**Setting:** `disable-model-invocation: true`

**What this means:**
- Agent will **NOT** automatically invoke Yatta! operations
- **User must explicitly request** each action
- No background task creation or modification
- All operations require clear user intent

### Why Manual-Only?

**Security rationale:**

1. **Full account access:** Yatta! API keys grant complete account access
2. **No read-only scopes:** No way to limit API key permissions
3. **Destructive operations:** Can delete/archive/modify data permanently
4. **User oversight required:** Changes should be reviewed before execution

### Examples

**❌ Autonomous (NOT allowed):**
```
User: "I should probably archive old tasks"
Agent: *silently archives tasks without confirmation*
```

**✅ Manual (Required):**
```
User: "Please archive tasks older than 30 days"
Agent: *executes explicit request, shows results*
```

### Policy Enforcement

**How it works:**
1. Skill metadata declares `disable-model-invocation: true`
2. OpenClaw respects this setting
3. Agent requires explicit user commands
4. No autonomous background operations

**Verification:**
```bash
# Check package.json
jq '.openclaw["disable-model-invocation"]' package.json
# Should output: true

# Check SKILL.md frontmatter
grep "disable-model-invocation" SKILL.md
# Should show: "disable-model-invocation":true
```

### If You See Unexpected Operations

**If Yatta! operations happen without your explicit request:**

1. **Stop immediately** - This indicates a policy violation
2. **Revoke API key** - Create new key in Yatta! Settings → API Keys
3. **File issue** - https://github.com/chrisagiddings/openclaw-yatta-skill/issues
4. **Report to OpenClaw*