task-create skill

---
name: task-create
description: Distill a conversation into a comprehensive task briefing for the project queue
---

# Task Create Skill

**Triggers:** "task this", "create task", "add task", "queue this"

## Purpose

Distill a conversation into a **comprehensive task briefing** and commit it to the active project's `tasks/` directory. The briefing gives a future agent (or the user themselves) everything needed to pick up the work cold — the context, the reasoning, the approach, and the acceptance criteria — without re-deriving any of it from scratch.

This skill generates **structured tasks**. It does NOT replace the existing simple task path (voice/API quick-drops that are just a title + priority). Both formats coexist in the same `tasks/` directory.

## Flow

1. **Scan conversation** — identify the problem, the discussion, any proposed solutions, files mentioned, decisions made, and constraints expressed
2. **Generate task JSON** following the comprehensive format below
3. **Show to user** for approval — print the full JSON, ask if it looks right
4. **On approval:** write to `tasks/{nextId}/task.json`, update `tasks/_registry.json`

## Task Format

```json
{
  "id": 46,
  "title": "Short imperative description (under 100 chars)",
  "context": "Background situation. What was happening when this came up. Sets the stage for someone reading this cold.",
  "why": "The user impact or need. Why this matters. Not the technical gap — the tangible problem or opportunity.",
  "what": "Concrete deliverable. What gets built, changed, or fixed. Specific enough to scope the work.",
  "how": "Architectural approach, key decisions, patterns to follow, things to avoid. Only if discussed. Empty string if open-ended.",
  "benefits": [
    "Tangible benefit 1 — what improves for the user",
    "Tangible benefit 2"
  ],
  "risks": [
    "What could go wrong or what to watch out for"
  ],
  "specialConditions": "Coordination needs, dependencies on other tasks, timing constraints, multi-agent considerations. Empty string if none.",
  "strategy": "Suggested implementation sequence or phasing. How to approach the work. Empty string if the agent should figure it out.",
  "checklist": [
    "Actionable step or sub-deliverable 1",
    "Actionable step or sub-deliverable 2"
  ],
  "verification": [
    "How to confirm this works — what to test, what to observe",
    "Second verification step"
  ],
  "example": "A quick concrete scenario illustrating the expected behavior or outcome. Drives the point home. Empty string if not applicable.",
  "files": ["src/App.tsx", "scripts/project_api.py"],
  "done_when": "1-2 tangible statements. What the user would see or verify. The exit criteria.",
  "status": "pending",
  "priority": "medium",
  "assignedProject": "/home/yousuf/local_workspaces/<project>",
  "createdAt": "YYYY-MM-DDTHH:MM:SS"
}
```

## "Where Applicable" Principle

Not every section applies to every task. **Use judgment.** A bug fix might not need `benefits` or `strategy`. A feature idea with no discussed approach can leave `how` and `strategy` empty. A simple refactor might skip `risks`.

**Always required:** `id`, `title`, `context`, `why`, `what`, `done_when`, `status`, `priority`, `assignedProject`, `createdAt`

**Include when relevant:** `how`, `benefits`, `risks`, `specialConditions`, `strategy`, `checklist`, `verification`, `example`, `files`

**Omit vs empty:** If a section genuinely doesn't apply, omit the key entirely rather than leaving an empty string or empty array. Exception: `files` always present (use `[]` if unknown).

## Field Guidelines

### title
- Imperative form: "Add multi-tab support", not "Multi-tab support should be added"
- Under 100 chars
- Specific enough that reading just the title tells you what to build
- BAD: "Fix the thing we discussed"
- GOOD: "Fix dead terminals appearing when switching projects"

### context
- Sets the stage. What was the user doing when this came up? What had just happened?
- Written for someone with zero prior knowledge of the conversation
- 2-4 sentences. Include relevant system state or environmental details
- BAD: "We were talking about tabs"
- GOOD: "User accesses TriClaude via Chrome on port 3443. When opening multiple tabs to work on different projects simultaneously, both tabs share the same activeProjectId and localStorage, causing project switches in one tab to affect the other."

### why
- The human-level need or pain point, not the technical root cause
- Written from user perspective
- BAD: "activeProjectId is a singleton in the backend config"
- GOOD: "User can't work on two projects simultaneously — switching in one tab disrupts the other"

### what
- The concrete deliverable or change
- Specific enough to scope the work but not so detailed it becomes implementation steps
- BAD: "Fix the multi-tab problem"
- GOOD: "Per-tab session isolation so each Chrome tab maintains its own active project, localStorage namespace, and WebSocket scope independently"

### how
- Architectural approach discussed during the conversation
- Capture **decisions and constraints**, not step-by-step instructions (the agent figures out steps)
- Include user preferences and things explicitly ruled out
- Empty string `""` if no approach was discussed — the task is an open problem
- BAD: "Step 1: open App.tsx. Step 2: find line 43..."
- GOOD: "Use sessionStorage for per-tab ID generated on load. Backend tracks activeProjectId per session instead of globally. localStorage keys namespaced by session ID. Avoid breaking existing single-tab behavior."

### benefits
- Array of tangible improvements, not vague promises
- Each item should answer "what gets better for the user?"
- BAD: `["Better architecture", "Cleaner code"]`
- GOOD: `["Can work on frontend and backend projects simultaneously without interference", "No more workaround of Chrome + Incognito windows"]`

### risks
- Array of things that could go wrong, edge cases, or gotchas
- Include things the future agent should watch out for
- BAD: `["Might be hard"]`
- GOOD: `["Existing localStorage data from single-tab era needs migration or graceful fallback", "WebSocket reconnection logic assumes single active project — needs session scoping"]`

### specialConditions
- Coordination needs (other agents working on same files, multi-agent locks)
- Dependencies on other tasks (by ID or description)
- Timing constraints (must ship before X, blocked until Y)
- Environmental requirements (needs API restart, requires specific device testing)
- Empty string if none apply

### strategy
- Suggested implementation sequence or phasing
- Useful when the work has a natural order or when early wins can be shipped independently
- BAD: "Just do it"
- GOOD: "Phase 1: sessionStorage ID generation + localStorage namespacing (frontend only, no backend changes). Phase 2: Backend session tracking for activeProjectId. Phase 3: WebSocket scoping. Each phase is independently shippable."

### checklist
- Array of actionable sub-deliverables or implementation steps
- Serves as a guide, not a rigid contract — the agent can adapt
- Each item should be checkable (done or not done)
- **Checklists are live.** Items can be toggled done/undone via the tasks API. Task status auto-derives from checklist progress: 0 done = `pending`, 1+ done = `in_progress`, all done = `completed`
- **Agents must update checklist items as they work.** See "Checklist Maintenance" below
- Items start as plain strings. When toggled, they become `{"text": "...", "done": true/false}`
- BAD: `["Think about the problem", "Write some code"]`
- GOOD: `["Generate session ID in sessionStorage on App mount", "Namespace all localStorage keys with session prefix", "Pass session ID in API calls for activeProjectId tracking", "Scope WebSocket subscriptions to session", "Test: two tabs showing different projects independently"]`

### verification
- Array of concrete ways to confirm the work is complete
- What to test, what to observe, what should be true after
- BAD: `["Make sure it works"]`
- GOOD: `["Open two Chrome tabs on port 3443", "Set tab 1 to project A and tab 2 to project B", "Switch projects in tab 1 — tab 2 should remain on project B", "Refresh tab 2 — should still show project B, not project A"]`

### example
- A quick concrete scenario that illustrates the expected behavior
- Drives the point home for someone who might misinterpret the abstract description
- Keep it short — 2-5 sentences
- Empty string if the task is self-explanatory

### files
- List of files/areas the task would touch (best guess from conversation)
- Helps future agent skip exploration and go straight to the right code
- `[]` if unknown

### done_when
- What the user would see, click, or verify. The exit criteria.
- BAD: "Refactored localStorage calls to use sessionStorage"
- GOOD: "Two Chrome tabs show different projects independently without state collision"

### priority
- `"high"` — blocking current work or user-critical
- `"medium"` — would be nice, should get to it
- `"low"` — someday/maybe

## Registry Update

After writing the task file, update `tasks/_registry.json`:
1. Read current registry
2. Increment `nextId`
3. Append new task ID to `tasks` array
4. Write back

```python
# Example
registry["nextId"] = new_id + 1
registry["tasks"].append(new_id)
```

## Detection: When to Suggest

If the conversation includes phrases like:
- "we should do that later"
- "add that to the backlog"
- "queue that for future"
- "that's a future thing"
- "not now but eventually"
- "let's come back to this"

...proactively suggest: "Want me to task this for the project queue?"

## Full Example

User discusses dead terminals persisting across project switches. Investigation reveals the persist effect saves old project's panels under the new project's localStorage key during the switch. Solution discussed: guard the save effect with a prevActiveProjectId check, and have auto-populate remove stale agent panels.

```json
{
  "id": 43,
  "title": "Fix dead terminals appearing when switching projects",
  "context": "In single-project mode, the user switches between projects frequently. After switching, terminals from the previous project appear as dead/unclosable panels in the new project's view. The persist effect in App.tsx fires when activeProjectId changes but spPanels still holds old project data, writing it to the new project's localStorage key.",
  "why": "Switching between projects shows orphaned terminals that can't be closed, cluttering the workspace and requiring manual localStorage cleanup.",
  "what": "Guard the panel persist effect against cross-project writes, and add stale panel cleanup to the auto-populate logic.",
  "how": "Two changes in App.tsx: (1) The persist effect should compare prevActiveProjectId with current before saving — skip if they differ. (2) Auto-populate should filter out agent panels whose terminalId doesn't exist in the current project's terminal list.",
  "benefits": [
    "Clean workspace after every project switch — no orphaned panels",
    "No more manual localStorage cleanup needed"
  ],
  "risks": [
    "Must preserve the ref tracking for prevActiveProjectId — if the ref update races with the effect, panels could still leak",
    "Aggressive cleanup might remove panels during the brief moment between project switch and terminal list refresh"
  ],
  "specialConditions": "The persist effect and auto-populate effect both touch spPanels state — changes must not introduce render loops.",
  "checklist": [
    "Add prevActiveProjectId ref to App.tsx",
    "Guard persist effect: skip save when project ID is mid-switch",
    "Auto-populate: filter agent panels where terminalId not in active project's terminal list",
    "Test: switch projects 3 times rapidly, verify no dead panels"
  ],
  "verification": [
    "Switch from project A (with 2 terminals) to project B — project B should show only its own terminals",
    "Switch back to project A — should show its 2 terminals, no extras from B",
    "Rapid switch A→B→A — no dead panels accumulate"
  ],
  "files": ["src/App.tsx"],
  "done_when": "Switching between projects shows only the current project's terminals. No dead panels appear.",
  "status": "pending",
  "priority": "high",
  "assignedProject": "/home/yousuf/local_workspaces/triclaude",
  "createdAt": "2026-02-15T14:00:00"
}
```

## Checklist Maintenance (Agent Protocol)

Checklists are **live tracking instruments**, not just planning artifacts. Task status auto-derives from checklist progress:

| Done count | Task status |
|------------|-------------|
| 0 of N | `pending` |
| 1+ of N | `in_progress` |
| N of N | `completed` |

### Agent responsibilities during task execution

1. **On starting a task:** read the checklist, understand the scope
2. **On completing a checklist item:** toggle it done via the API immediately — don't batch updates at the end
3. **On scope adjustment:** update checklist items (add, modify, or remove) via the API. Minor adjustments are expected; major scope changes should be a new task
4. **On finishing:** verify all items are toggled. The backend auto-completes the task when all items are done

### API for checklist updates

```bash
curl -X POST http://localhost:7690/api/tasks/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "/home/yousuf/local_workspaces/<project>",
    "checklist": [
      {"text": "First item", "done": true},
      {"text": "Second item", "done": false},
      "Third item (plain string = not done)"
    ]
  }'
```

The backend merges incoming fields with existing task data — only the fields you send get updated. All other comprehensive fields (context, why, how, etc.) are preserved.

### What NOT to do
- Don't wait until the end to toggle everything at once — the user watches progress in real time
- Don't create a new task just because a checklist item needs rewording — update the item text
- Don't manually set `status` when updating checklist — the backend derives it automatically

## Compatibility Note

This comprehensive format is for **skill-generated tasks only**. Simple tasks created via voice, the API, or manual entry will continue to use whatever fields they have (often just `title`, `status`, `priority`). Both formats are valid in `tasks/` and the registry treats them identically. The agent picking up the task adapts to whichever format it finds.