opentasks 0.1.3 → 0.2.0

package/skills/opentasks/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: opentasks
+description: Use when managing work items, linking external data (Slack, docs, URLs) to tasks, querying task dependencies or blockers, leaving cross-system feedback on specs or issues, or coordinating work across multiple task systems. Use when the agent has access to the `opentasks` CLI.
+user-invocable: false
+---
+
+# OpenTasks
+
+OpenTasks is a graph connector that adds a relationship layer across task systems. It does not replace those systems — it provides cross-system edges, feedback, and dependency tracking.
+
+## CLI Commands
+
+All operations go through the `opentasks` CLI, which talks to the daemon over IPC.
+
+### Link — create or remove edges
+
+```bash
+opentasks link --from t-x7k9 --to c-a2b3 --type implements
+opentasks link --from t-x7k9 --to t-m4n5 --type blocks
+opentasks link --from t-x7k9 --to e-k7m2 --type references --metadata '{"context":"bug report"}'
+opentasks link --from t-aaa --to t-bbb --type blocks --remove
+```
+
+Returns `{ success, edgeId? }`. Idempotent. `blocks` edges are cycle-checked.
+
+### Query — search nodes, edges, blockers, ready work
+
+```bash
+opentasks query '{"ready": {}}'
+opentasks query '{"blockers": {"nodeId": "t-r8s9", "activeOnly": true}}'
+opentasks query '{"blocking": {"nodeId": "t-x7k9", "transitive": true}}'
+opentasks query '{"edges": {"from_id": "t-x7k9", "type": "references"}}'
+opentasks query '{"tasks": {"specId": "c-a2b3"}}'
+opentasks query '{"feedback": {"nodeId": "c-a2b3", "resolved": false}}'
+opentasks query '{"unresolvedFeedback": {}}'
+```
+
+Exactly one query key per call. Returns `{ items, total?, hasMore }`.
+
+| Key | Purpose |
+|-----|---------|
+| `nodes` | Filter nodes by type, status, tags, search |
+| `edges` | Filter edges by from_id, to_id, type |
+| `ready` | Unblocked open tasks (tags?, priority?, assignee?) |
+| `blockers` | What blocks a node (transitive?, activeOnly?) |
+| `blocking` | What a node blocks (transitive?) |
+| `feedback` | Feedback on a node (type?, resolved?) |
+| `unresolvedFeedback` | All unresolved feedback (targetId?) |
+| `tasks` | Tasks implementing a context (specId) |
+| `specs` | Specs a task implements (issueId) |
+
+### Annotate — feedback lifecycle
+
+```bash
+# Create feedback
+opentasks annotate '{"targetId":"c-a2b3","create":{"content":"Implemented OAuth.","type":"comment"}}'
+
+# With source issue link
+opentasks annotate '{"targetId":"c-a2b3","fromId":"t-x7k9","create":{"content":"Done.","type":"comment"}}'
+
+# Anchored suggestion
+opentasks annotate '{"targetId":"c-a2b3","create":{"content":"Add rate limiting","type":"suggestion","anchor":{"line":15}}}'
+
+# Resolve / dismiss / reopen
+opentasks annotate '{"targetId":"c-a2b3","resolve":"f-t1u2"}'
+opentasks annotate '{"targetId":"c-a2b3","dismiss":"f-t1u2"}'
+opentasks annotate '{"targetId":"c-a2b3","reopen":"f-t1u2"}'
+```
+
+### Create — add nodes
+
+```bash
+opentasks create --type task --title "Fix SSO redirect" --status open --tags auth,bug --priority 1
+opentasks create --type context --title "OAuth2 for API" --status active --content "## Requirements\n..."
+opentasks create --type external --title "Slack: SSO bug" --uri "slack://C04ABCD/p123" --source slack --metadata '{"author":"alex"}'
+```
+
+### Get / Update / Delete
+
+```bash
+opentasks get t-x7k9
+opentasks update t-x7k9 --status closed
+opentasks update t-x7k9 --title "New title" --metadata '{"key":"val"}'
+opentasks delete t-x7k9
+opentasks delete t-x7k9 --hard
+```
+
+## Node Types
+
+| Type | Prefix | Required | Purpose |
+|------|--------|----------|---------|
+| `context` | `c-` | title | Requirements, specs, intent (inline or file-backed) |
+| `task` | `t-` | title, status | Actionable work items |
+| `feedback` | `f-` | title, target_id, feedback_type | Comments, suggestions, requests |
+| `external` | `e-` | title, uri, source | References to external systems |
+
+All nodes support optional: `content`, `priority` (0-4), `tags[]`, `parent_id`, `metadata`.
+
+## Context Sources
+
+Context nodes support multiple content source types. The source type determines how content is stored and resolved.
+
+| Source | Stored in node? | How content is accessed |
+|--------|-----------------|------------------------|
+| inline (default) | Yes, in `content` field | Read directly from the node |
+| file | No (pointer only) | Resolved from the working tree or a pinned git commit |
+| snippet | No (pointer only) | Resolved from specific line range in a file |
+
+### Inline context (default)
+
+Content is stored directly in the node. Use for design decisions, requirements written by agents, meeting notes, etc.
+
+```bash
+# CLI
+opentasks create --type context --title "OAuth2 for API" --content "## Requirements\n..."
+```
+
+```json
+// MCP: create_context
+{ "title": "OAuth2 for API", "content": "## Requirements\n..." }
+```
+
+### File-backed context
+
+References a codebase file. Content is NOT stored — it's resolved on access from the working tree or at a specific git commit. Includes drift detection (has the file changed since it was captured?).
+
+```json
+// MCP: create_context with source
+{
+  "title": "Auth Middleware",
+  "source": { "type": "file", "path": "src/auth/middleware.ts" },
+  "tags": ["auth"]
+}
+
+// Pin to a specific commit
+{
+  "source": { "type": "file", "path": "src/auth/middleware.ts", "commit": "abc123" }
+}
+```
+
+### Snippet context
+
+References specific lines in a file. Like file-backed, but scoped to a line range.
+
+```json
+// MCP: create_context with snippet source
+{
+  "title": "Token validation logic",
+  "source": { "type": "snippet", "path": "src/auth/middleware.ts", "startLine": 42, "endLine": 58 }
+}
+```
+
+### Resolving content
+
+File and snippet contexts don't store content. Use `get_context` with `resolve: true` to fetch the current file content.
+
+```json
+// MCP: get_context — lightweight (metadata only, no file I/O)
+{ "id": "c-x7k9" }
+
+// MCP: get_context — with file content resolved
+{ "id": "c-x7k9", "resolve": true }
+
+// MCP: get_context — content at the originally captured commit
+{ "id": "c-x7k9", "resolve": true, "atCapturedCommit": true }
+```
+
+The response includes `_resolved.drifted: true/false` indicating whether the file has changed since capture.
+
+### Syncing and drift detection
+
+```json
+// MCP: update_context — re-pin to current HEAD
+{ "id": "c-x7k9", "sync": true }
+
+// MCP: update_context — force re-pin even if unchanged
+{ "id": "c-x7k9", "sync": true, "force": true }
+
+// MCP: list_contexts — check drift for all file-backed contexts
+{ "checkDrift": true }
+
+// MCP: list_contexts — only file-backed contexts
+{ "filesOnly": true, "checkDrift": true }
+```
+
+## Edge Types
+
+| Type | Semantics | Cycle-checked |
+|------|-----------|---------------|
+| `blocks` | from must complete before to can start | Yes |
+| `implements` | task implements context | No |
+| `references` | general reference | No |
+| `related` | loose association | No |
+| `child-of` | hierarchical containment | No |
+| `parent-of` | inverse of child-of | No |
+| `depends-on` | soft dependency (informational, not used by `ready`) | No |
+| `discovered-from` | found while working on | No |
+| `duplicates` | from is duplicate of to | No |
+| `supersedes` | from replaces to | No |
+
+Edge types are extensible via string.
+
+## URI Conventions
+
+Nodes across systems are identified by URIs:
+
+```
+native://c-a2b3                    # OpenTasks native node
+beads://./bd-x7k9                  # Beads issue
+taskmaster://./auth-prd            # Taskmaster spec
+claude://current/t-abc             # Claude task
+slack://C04ABCD/p1234567890        # Slack message (custom)
+github://owner/repo/pull/42        # GitHub PR (custom)
+```
+
+The `uri` field on ExternalNodes is freeform. Use consistent schemes for deduplication.
+
+## Specialized Workflows
+
+**Linking external data** (Slack messages, docs, URLs): See [linking-external-data.md](linking-external-data.md)
+
+**Spec to implementation** (create spec, break into issues, track to completion): See [spec-to-implementation.md](spec-to-implementation.md)
+
+**Feedback and review** (cross-system feedback, suggestion lifecycle): See [feedback-and-review.md](feedback-and-review.md)
+
+**Dependency management** (blockers, ready queries, work loops): See [dependency-management.md](dependency-management.md)

package/skills/opentasks/dependency-management.md

@@ -0,0 +1,119 @@
+# Dependency Management
+
+Set up dependency chains, query what's blocked and ready, manage work ordering.
+
+## blocks vs depends-on
+
+| Edge | Used by `ready` query | Cycle-checked | Use when |
+|------|----------------------|---------------|----------|
+| `blocks` | Yes | Yes | Work genuinely can't start until blocker closes |
+| `depends-on` | No | No | "Nice to have first" but not strictly required |
+
+## Setting Up Dependencies
+
+### Linear chain: A → B → C → D
+
+```bash
+opentasks link --from t-aaa --to t-bbb --type blocks
+opentasks link --from t-bbb --to t-ccc --type blocks
+opentasks link --from t-ccc --to t-ddd --type blocks
+```
+
+### Diamond: A blocks B+C, both block D
+
+```bash
+opentasks link --from t-aaa --to t-bbb --type blocks
+opentasks link --from t-aaa --to t-ccc --type blocks
+opentasks link --from t-bbb --to t-ddd --type blocks
+opentasks link --from t-ccc --to t-ddd --type blocks
+```
+
+B and C can run in parallel once A closes. D waits for both.
+
+### Cycle detection
+
+Creating a `blocks` edge that would form a cycle returns an error:
+
+```bash
+# Given: A blocks B, B blocks C
+opentasks link --from t-ccc --to t-aaa --type blocks
+# → { success: false, error: "Would create circular dependency" }
+```
+
+### Removing dependencies
+
+```bash
+opentasks link --from t-aaa --to t-bbb --type blocks --remove
+```
+
+## Querying
+
+### What blocks a node?
+
+```bash
+# Direct blockers
+opentasks query '{"blockers": {"nodeId": "t-ddd"}}'
+
+# Full chain (transitive)
+opentasks query '{"blockers": {"nodeId": "t-ddd", "transitive": true}}'
+
+# Only active (non-closed, non-archived)
+opentasks query '{"blockers": {"nodeId": "t-ddd", "activeOnly": true}}'
+```
+
+### What does a node block?
+
+```bash
+opentasks query '{"blocking": {"nodeId": "t-aaa", "transitive": true}}'
+```
+
+### What's ready to work on?
+
+Returns open tasks with zero active blockers.
+
+```bash
+# All ready work
+opentasks query '{"ready": {}}'
+
+# Filtered
+opentasks query '{"ready": {"tags": ["auth"], "priority": {"min": 0, "max": 2}, "limit": 5}}'
+```
+
+## Agent Work Loop
+
+```
+loop:
+  1. opentasks query '{"ready": {"limit": 1}}'       → pick highest-priority unblocked issue
+  2. If empty, stop.
+  3. opentasks update t-x7k9 --status in_progress
+  4. Do the work.
+  5. opentasks update t-x7k9 --status closed
+  6. opentasks query '{"blocking": {"nodeId": "t-x7k9"}}'  → see what's now unblocked
+  7. Repeat.
+```
+
+## Cross-System Dependencies
+
+`blocks` edges work across systems. The `ready` query evaluates them uniformly.
+
+```bash
+opentasks link --from "beads://./bd-setup" --to t-x7k9 --type blocks
+opentasks link --from t-x7k9 --to "claude://current/t-abc" --type blocks
+```
+
+## Discovering Work During Implementation
+
+```bash
+# Create the discovered task
+opentasks create --type task --title "Token refresh fails for expired sessions" --status open --tags auth,bug --priority 1
+# → t-new1
+
+# Link to where it was discovered
+opentasks link --from t-new1 --to t-x7k9 --type discovered-from
+
+# If it blocks current work:
+opentasks link --from t-new1 --to t-x7k9 --type blocks
+
+# Update original to blocked
+opentasks update t-x7k9 --status blocked
+```

package/skills/opentasks/feedback-and-review.md

@@ -0,0 +1,100 @@
+# Feedback and Review
+
+Leave feedback on context and tasks, manage suggestion lifecycles, query unresolved items.
+
+## Feedback Types
+
+| Type | Use For |
+|------|---------|
+| `comment` | Status updates, implementation notes, observations |
+| `suggestion` | Proposed changes to target content |
+| `request` | Action needed — blocking questions, approvals |
+
+## Creating Feedback
+
+### Basic comment
+
+```bash
+opentasks annotate '{"targetId":"c-a2b3","create":{"content":"Implemented OAuth. Deferred SAML to follow-up.","type":"comment"}}'
+```
+
+### Implementation feedback (linked to source issue)
+
+```bash
+opentasks annotate '{"targetId":"c-a2b3","fromId":"t-x7k9","create":{"content":"Google OAuth requires access_type=offline for refresh tokens — added to config.","type":"comment"}}'
+```
+
+`fromId` creates a link from the task to the feedback for traceability.
+
+### Anchored suggestion
+
+```bash
+opentasks annotate '{"targetId":"c-a2b3","create":{"content":"Rate limiting needed here — OAuth endpoints are brute-force targets.","type":"suggestion","anchor":{"line":15,"text":"OAuth2 endpoints"}}}'
+```
+
+Anchors use `line` (exact), `text` (fuzzy match), or both. Text anchors survive content edits better.
+
+### Blocking request
+
+```bash
+opentasks annotate '{"targetId":"c-a2b3","create":{"content":"Which GitHub OAuth scopes? Spec says user profile but integration may need repo access.","type":"request"}}'
+```
+
+## Querying Feedback
+
+```bash
+# All feedback on a node
+opentasks query '{"feedback": {"nodeId": "c-a2b3"}}'
+
+# Unresolved suggestions only
+opentasks query '{"feedback": {"nodeId": "c-a2b3", "type": "suggestion", "resolved": false}}'
+
+# All unresolved feedback globally
+opentasks query '{"unresolvedFeedback": {}}'
+
+# Unresolved feedback for a specific target
+opentasks query '{"unresolvedFeedback": {"targetId": "c-a2b3"}}'
+```
+
+## Lifecycle Management
+
+```bash
+# Resolve (addressed)
+opentasks annotate '{"targetId":"c-a2b3","resolve":"f-t1u2"}'
+
+# Dismiss (not applicable)
+opentasks annotate '{"targetId":"c-a2b3","dismiss":"f-t1u2"}'
+
+# Reopen
+opentasks annotate '{"targetId":"c-a2b3","reopen":"f-t1u2"}'
+```
+
+## Review Workflow
+
+```bash
+# 1. Read spec
+opentasks get c-a2b3
+
+# 2. Check existing feedback
+opentasks query '{"feedback": {"nodeId": "c-a2b3"}}'
+
+# 3. Leave feedback
+opentasks annotate '{"targetId":"c-a2b3","create":{"content":"...","type":"comment"}}'
+
+# 4. Before implementing — check unresolved
+opentasks query '{"feedback": {"nodeId": "c-a2b3", "resolved": false}}'
+
+# 5. After addressing — resolve
+opentasks annotate '{"targetId":"c-a2b3","resolve":"f-abc1"}'
+```
+
+## Cross-System Feedback
+
+When source and target are in different systems, OpenTasks stores the feedback (native systems can't handle cross-refs).
+
+```bash
+# Beads issue commenting on Taskmaster spec
+opentasks annotate '{"targetId":"taskmaster://./auth-prd","fromId":"beads://./bd-x7k9","create":{"content":"Sections 1-3 done. Section 4 descoped.","type":"comment"}}'
+```
+
+Same-system feedback routes to native comments when the provider supports them.

package/skills/opentasks/linking-external-data.md

@@ -0,0 +1,103 @@
+# Linking External Data
+
+Bind non-task artifacts — Slack messages, Google Docs, Notion pages, emails, URLs — to context and tasks in the graph.
+
+## Pattern
+
+Two steps: create an ExternalNode, then link it.
+
+### 1. Create the ExternalNode
+
+```bash
+opentasks create --type external \
+  --title "Alex: SSO redirect loop after IdP response" \
+  --uri "slack://C04ABCD/p1234567890" \
+  --source slack \
+  --metadata '{"channel_name":"#engineering","permalink":"https://workspace.slack.com/archives/C04ABCD/p1234567890","author":"alex","text":"auth flow is broken for SSO users — getting redirect loop after IdP response"}'
+# → { id: "e-k7m2", ... }
+```
+
+### 2. Link to the relevant node
+
+```bash
+opentasks link --from t-x7k9 --to e-k7m2 --type references \
+  --metadata '{"context":"Original bug report from #engineering"}'
+```
+
+## URI Conventions
+
+The `uri` field is freeform. Consistent schemes enable deduplication.
+
+| Source | Format | Example |
+|--------|--------|---------|
+| Slack message | `slack://[channel]/p[ts]` | `slack://C04ABCD/p1234567890` |
+| Slack thread | `slack://[channel]/t[thread_ts]` | `slack://C04ABCD/t1234567880` |
+| Google Doc | `gdoc://[doc-id]` | `gdoc://1BxiMVs0XRA5nF...` |
+| Notion page | `notion://[page-id]` | `notion://a1b2c3d4-e5f6-...` |
+| Figma file | `figma://[file-key]` | `figma://abc123DEF456` |
+| GitHub PR | `github://[owner]/[repo]/pull/[num]` | `github://org/repo/pull/42` |
+| Generic URL | `web://[url]` | `web://example.com/page` |
+
+## Edge Type Selection
+
+| Situation | Edge Type |
+|-----------|-----------|
+| Bug report, source document | `references` |
+| Found during investigation | `discovered-from` |
+| Loosely related context | `related` |
+
+Direction: typically `issue → external` or `spec → external`.
+
+## Deduplication
+
+Check before creating:
+
+```bash
+opentasks query '{"nodes": {"type": "external", "search": "slack://C04ABCD/p1234567890"}}'
+```
+
+If a node with that URI exists, skip creation and link to the existing node.
+
+## Phantom Nodes (URL only)
+
+If the agent only has a URL and can't fetch content:
+
+```bash
+opentasks create --type external \
+  --title "Related Slack thread" \
+  --uri "slack://C04ABCD/t1234567880" \
+  --source slack \
+  --metadata '{"permalink":"https://workspace.slack.com/archives/C04ABCD/p1234567880"}'
+```
+
+An agent with access to the external system can later enrich via `opentasks update`.
+
+## Querying Linked Data
+
+```bash
+# All references from a task
+opentasks query '{"edges": {"from_id": "t-x7k9", "type": "references"}}'
+
+# All external nodes from Slack
+opentasks query '{"nodes": {"type": "external", "search": "slack"}}'
+```
+
+## Complete Example
+
+```
+Agent working on "Fix SSO redirect loop":
+
+1. Search Slack via MCP → find 3 relevant messages
+
+2. For each, create ExternalNode:
+   opentasks create --type external --title "..." --uri "slack://..." --source slack --metadata '{...}'
+
+3. Link each to the task:
+   opentasks link --from t-x7k9 --to e-k7m2 --type references
+   opentasks link --from t-x7k9 --to e-k7m3 --type references
+   opentasks link --from t-x7k9 --to e-k7m4 --type discovered-from
+
+4. Later, another agent queries context:
+   opentasks query '{"edges": {"from_id": "t-x7k9", "type": ["references", "discovered-from"]}}'
+   → Gets back ExternalNodes with Slack content in metadata
+```