npm - claude-code-swarm - Versions diffs - 0.3.7 → 0.3.8 - Mend

claude-code-swarm 0.3.7 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1357) hide show

package/references/opentasks/docs/INTERFACE.md DELETED Viewed

@@ -1,670 +0,0 @@
-# OpenTasks Agent Interface
-This document defines the programmatic interface for interacting with OpenTasks.
-See also:
-- [DESIGN.md](./DESIGN.md) — Design rationale and core concepts
-- [SCHEMA.md](./SCHEMA.md) — Data model and types
-- [PERSISTENCE.md](./PERSISTENCE.md) — Storage and sync
-- [ARCHITECTURE.md](./ARCHITECTURE.md) — Location hierarchy and daemon
-- [PROVIDERS.md](./PROVIDERS.md) — Provider integration
----
-## Design Philosophy
-OpenTasks is a **graph connector** that adds a relationship layer to existing task systems. It does not replace those systems — each keeps its own tools, storage, and semantics. OpenTasks provides what they lack: cross-system edges.
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     Agent Working Session                        │
-│                                                                  │
-│  Native Systems (each with their own interface):                 │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
-│  │  Claude Tasks   │  │     Beads       │  │   Taskmaster    │  │
-│  │                 │  │                 │  │                 │  │
-│  │ • Subtasks      │  │ • Persistent    │  │ • PRD specs     │  │
-│  │ • Session-scoped│  │ • Multi-agent   │  │ • Task breakdown│  │
-│  │ • Immediate     │  │ • Git-tracked   │  │ • Planning      │  │
-│  │ • Ephemeral     │  │ • Rich deps     │  │                 │  │
-│  │                 │  │                 │  │                 │  │
-│  │ TaskCreate()    │  │ bd new          │  │ tm task         │  │
-│  │ TaskUpdate()    │  │ bd update       │  │ tm prd          │  │
-│  │ TaskGet()       │  │ bd show         │  │                 │  │
-│  │ TaskList()      │  │ bd list         │  │                 │  │
-│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
-│           │                   │                   │              │
-│           └───────────────────┼───────────────────┘              │
-│                               │                                  │
-│                               ▼                                  │
-│  ┌─────────────────────────────────────────────────────────────┐│
-│  │                    OpenTasks (Graph Layer)                   ││
-│  │                                                              ││
-│  │  • Links nodes across systems                                ││
-│  │  • Queries relationships (blockers, tasks, ready)     ││
-│  │  • Stores cross-system feedback                              ││
-│  │  • Maintains node registry with cached metadata              ││
-│  │                                                              ││
-│  │  3 Tools: link, query, annotate                              ││
-│  └─────────────────────────────────────────────────────────────┘│
-└─────────────────────────────────────────────────────────────────┘
-```
-### What OpenTasks Owns
-| Component | Description |
-|-----------|-------------|
-| **Edges** | Relationships between nodes (any system) |
-| **Node Registry** | Tracks what exists where, with cached metadata |
-| **Cross-System Feedback** | Annotations that span system boundaries |
-### What OpenTasks Does NOT Own
-| Component | Owner |
-|-----------|-------|
-| **Task/Context CRUD** | Native systems (Claude Tasks, Beads, Linear, etc.) |
-| **Status Workflows** | Each system's semantics |
-| **Content Storage** | Providers own their data |
-| **Same-System Feedback** | Native comment systems (Beads comments, GH comments, etc.) |
----
-## URI Scheme
-All nodes are identified by URIs:
-```
-claude://[session]/[task-id]      # Claude Code task
-beads://[workspace]/[id]          # Beads issue
-taskmaster://[project]/[id]       # Taskmaster PRD/task
-linear://[team]/[id]              # Linear issue
-jira://[project]/[key]            # Jira issue
-github://[owner]/[repo]/[num]     # GitHub issue
-native://[type]/[id]              # OpenTasks native node
-```
-**Examples:**
-```
-claude://current/t-abc123         # Claude task in current session
-beads://./bd-x7k9                 # Beads issue in current workspace
-taskmaster://./auth-prd           # Taskmaster PRD
-linear://ENG/ENG-123              # Linear issue
-native://c-a2b3                   # Native OpenTasks context
-```
----
-## The 3-Tool Interface
-OpenTasks exposes three tools that provide the graph connectivity layer:
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      OpenTasks Tools                             │
-│                                                                  │
-│  ┌────────────────────────────────────────────────────────────┐ │
-│  │  link                                                       │ │
-│  │  Create or remove relationships between any nodes           │ │
-│  └────────────────────────────────────────────────────────────┘ │
-│                                                                  │
-│  ┌────────────────────────────────────────────────────────────┐ │
-│  │  query                                                      │ │
-│  │  Query the graph: edges, blockers, ready, resolve URIs      │ │
-│  └────────────────────────────────────────────────────────────┘ │
-│                                                                  │
-│  ┌────────────────────────────────────────────────────────────┐ │
-│  │  annotate                                                   │ │
-│  │  Add feedback, tags, or metadata to any node                │ │
-│  └────────────────────────────────────────────────────────────┘ │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
----
-## Tool: `link`
-Create or remove relationships between nodes across any systems.
-### Signature
-```typescript
-function link(params: LinkParams): LinkResult
-interface LinkParams {
-  // Create edge
-  from: string                    // Source URI
-  to: string                      // Target URI
-  type: EdgeType                  // Relationship type
-  // Optional
-  remove?: boolean                // If true, removes the edge instead
-  metadata?: Record<string, unknown>
-}
-type EdgeType =
-  | 'blocks'           // from must complete before to can start
-  | 'implements'       // task implements context
-  | 'child-of'         // hierarchical parent-child
-  | 'references'       // general reference
-  | 'related'          // loose association
-  | 'duplicates'       // marks duplicate
-  | 'supersedes'       // replaces another node
-  | 'depends-on'       // soft dependency (informational)
-  | 'discovered-from'  // found while working on
-  | string             // extensible
-interface LinkResult {
-  edge_id: string
-  from: string
-  to: string
-  type: EdgeType
-  created_at: string
-}
-```
-### Examples
-```typescript
-// Beads issue implements Taskmaster context
-link({
-  from: 'beads://./bd-x7k9',
-  to: 'taskmaster://./auth-prd',
-  type: 'implements'
-})
-// Claude subtask is child of Beads issue
-link({
-  from: 'claude://current/t-abc',
-  to: 'beads://./bd-x7k9',
-  type: 'child-of'
-})
-// One Beads issue blocks another
-link({
-  from: 'beads://./bd-setup',
-  to: 'beads://./bd-impl',
-  type: 'blocks'
-})
-// Remove a relationship
-link({
-  from: 'beads://./bd-setup',
-  to: 'beads://./bd-impl',
-  type: 'blocks',
-  remove: true
-})
-```
-### Behavior
-- **Idempotent**: Creating a duplicate edge returns the existing edge
-- **Cross-system**: Can link nodes from any registered provider
-- **Auto-registration**: Referenced URIs are automatically registered in the node registry
-- **Cycle detection**: Returns error if edge would create circular `blocks` dependency
----
-## Tool: `query`
-Query the graph for relationships, nodes, and computed views.
-### Signature
-```typescript
-function query(params: QueryParams): QueryResult
-interface QueryParams {
-  // What to find
-  find: QueryType
-  // Starting point (required for most query types)
-  node?: string                   // URI
-  // Filters
-  type?: EdgeType | EdgeType[]    // Filter by edge type
-  direction?: 'in' | 'out' | 'both'
-  providers?: string[]            // Filter by provider
-  status?: string | string[]      // Filter by status (canonical)
-  // Options
-  transitive?: boolean            // Follow chains (for blockers/blocking)
-  active_only?: boolean           // Only non-closed nodes
-  include_metadata?: boolean      // Include cached node metadata
-  limit?: number
-}
-type QueryType =
-  | 'edges'          // Get edges for a node
-  | 'blockers'       // What blocks this node?
-  | 'blocking'       // What does this node block?
-  | 'ready'          // What's ready to work on? (no active blockers)
-  | 'tasks'   // Tasks implementing a context
-  | 'context'          // Context that a task implements
-  | 'children'       // Child nodes
-  | 'parents'        // Parent nodes
-  | 'resolve'        // Get node metadata by URI
-type QueryResult = {
-  nodes?: NodeRef[]
-  edges?: Edge[]
-  node?: NodeRef      // For 'resolve' query
-}
-interface NodeRef {
-  uri: string
-  provider: string
-  title?: string
-  status?: string           // Canonical status
-  provider_status?: string  // Provider's actual status
-  type?: 'context' | 'task' | 'task' | 'feedback'
-  cached_at?: string
-  stale?: boolean
-}
-interface Edge {
-  id: string
-  from: string
-  to: string
-  type: EdgeType
-  created_at: string
-  metadata?: Record<string, unknown>
-}
-```
-### Query Types
-#### `edges` — Get relationships for a node
-```typescript
-// All edges for a Beads issue
-query({ find: 'edges', node: 'beads://./bd-x7k9' })
-// Only outgoing 'blocks' edges
-query({
-  find: 'edges',
-  node: 'beads://./bd-x7k9',
-  direction: 'out',
-  type: 'blocks'
-})
-```
-#### `blockers` — What blocks this node?
-```typescript
-// Direct blockers
-query({ find: 'blockers', node: 'beads://./bd-impl' })
-// Returns: [{ uri: 'beads://./bd-setup', title: 'Set up database', status: 'in_progress' }]
-// Transitive blockers (blockers of blockers)
-query({ find: 'blockers', node: 'beads://./bd-impl', transitive: true })
-// Only active blockers (not closed)
-query({ find: 'blockers', node: 'beads://./bd-impl', active_only: true })
-```
-#### `blocking` — What does this node block?
-```typescript
-query({ find: 'blocking', node: 'beads://./bd-setup' })
-// Returns nodes that are waiting on bd-setup
-```
-#### `ready` — What's ready to work on?
-```typescript
-// All ready work across all providers
-query({ find: 'ready' })
-// Ready work from specific providers
-query({ find: 'ready', providers: ['beads', 'claude'] })
-// Ready work with specific status
-query({ find: 'ready', status: 'open' })
-```
-**Ready logic:**
-1. Queries each provider for open/pending items
-2. Filters out items with active (non-closed) blockers in OpenTasks graph
-3. Returns unified list with provider metadata
-#### `tasks` — Tasks implementing a context
-```typescript
-query({ find: 'tasks', node: 'taskmaster://./auth-prd' })
-// Returns: [{ uri: 'beads://./bd-x7k9', title: 'Implement OAuth', ... }]
-```
-#### `context` — Context that a task implements
-```typescript
-query({ find: 'context', node: 'beads://./bd-x7k9' })
-// Returns: [{ uri: 'taskmaster://./auth-prd', title: 'Auth PRD', ... }]
-```
-#### `children` / `parents` — Hierarchical queries
-```typescript
-// Get subtasks of a Beads issue
-query({ find: 'children', node: 'beads://./bd-x7k9' })
-// Might return Claude tasks that are children
-// Get parent of a Claude task
-query({ find: 'parents', node: 'claude://current/t-abc' })
-```
-#### `resolve` — Get node metadata by URI
-```typescript
-query({ find: 'resolve', node: 'beads://./bd-x7k9' })
-// Returns: {
-//   node: { uri: 'beads://./bd-x7k9', provider: 'beads', title: '...', status: 'open', ... }
-// }
-// With fresh fetch (bypass cache)
-query({ find: 'resolve', node: 'beads://./bd-x7k9', include_metadata: true })
-```
----
-## Tool: `annotate`
-Add feedback, tags, or metadata to any node. Handles routing between native comment systems and OpenTasks storage.
-### Signature
-```typescript
-function annotate(params: AnnotateParams): AnnotateResult
-interface AnnotateParams {
-  // Target node
-  target: string                  // URI of node to annotate
-  // Source context (optional - for cross-system feedback)
-  source?: string                 // URI of node providing the feedback
-  // Annotation content (at least one required)
-  feedback?: {
-    content: string
-    type: 'comment' | 'suggestion' | 'request'
-    anchor?: Anchor
-  }
-  tags?: string[]                 // Add tags
-  metadata?: Record<string, unknown>  // Add metadata
-}
-interface Anchor {
-  line?: number                   // Line number (1-indexed)
-  text?: string                   // Text snippet for fuzzy matching
-  section?: string                // Section heading
-}
-interface AnnotateResult {
-  id: string
-  stored_in: 'opentasks' | 'native'
-  provider?: string               // If stored in native system
-  target: string
-  created_at: string
-}
-```
-### Feedback Routing
-Feedback is automatically routed based on context:
-| Scenario | Destination | Rationale |
-|----------|-------------|-----------|
-| Cross-system feedback (source and target in different systems) | OpenTasks | Native systems can't handle cross-refs |
-| Implementation feedback on context | OpenTasks | Anchored feedback with relocation |
-| Same-system, provider supports comments | Native | Keep feedback where it belongs |
-| Same-system, no comment support | OpenTasks | Fallback |
-### Examples
-```typescript
-// Cross-system feedback: Beads issue commenting on Taskmaster context
-annotate({
-  target: 'taskmaster://./auth-prd',
-  source: 'beads://./bd-x7k9',
-  feedback: {
-    content: 'Implemented Google OAuth; GitHub OAuth deferred to follow-up',
-    type: 'comment'
-  }
-})
-// Stored in: OpenTasks (cross-system)
-// Anchored suggestion on a context
-annotate({
-  target: 'taskmaster://./auth-prd',
-  feedback: {
-    content: 'Consider adding rate limiting for security',
-    type: 'suggestion',
-    anchor: { line: 15, text: 'OAuth2 endpoints' }
-  }
-})
-// Stored in: OpenTasks (anchored feedback)
-// Comment on Beads issue (same-system)
-annotate({
-  target: 'beads://./bd-x7k9',
-  feedback: {
-    content: 'Started implementation, ETA 2 hours',
-    type: 'comment'
-  }
-})
-// Stored in: Native (Beads comments)
-// Add tags to any node
-annotate({
-  target: 'beads://./bd-x7k9',
-  tags: ['urgent', 'security']
-})
-// Add metadata
-annotate({
-  target: 'claude://current/t-abc',
-  metadata: { estimated_minutes: 30 }
-})
-```
-### Querying Feedback
-Feedback can be queried via the `query` tool:
-```typescript
-query({
-  find: 'edges',
-  node: 'taskmaster://./auth-prd',
-  type: 'feedback'
-})
-```
-Or via provider-specific feedback aggregation (see PROVIDERS.md).
----
-## Complete Workflow Example
-An agent implementing a feature using multiple systems:
-```typescript
-// 1. PRD exists in Taskmaster (created via tm CLI)
-const prdUri = 'taskmaster://./auth-feature'
-// 2. Check what context exists
-const ctx = await query({ find: 'resolve', node: prdUri })
-console.log(ctx.node.title)  // "Authentication Feature PRD"
-// 3. Create main task in Beads (using bd CLI)
-// $ bd new -t "Implement OAuth2 authentication"
-const mainTask = 'beads://./bd-x7k9'
-// 4. Link task to context
-await link({
-  from: mainTask,
-  to: prdUri,
-  type: 'implements'
-})
-// 5. Break down into Claude subtasks for immediate work
-const subtask1 = TaskCreate({
-  subject: 'Set up OAuth provider config',
-  description: '...'
-})
-const subtask2 = TaskCreate({
-  subject: 'Implement login endpoint',
-  description: '...'
-})
-// 6. Link subtasks to parent Beads task
-await link({
-  from: `claude://current/${subtask1.id}`,
-  to: mainTask,
-  type: 'child-of'
-})
-await link({
-  from: `claude://current/${subtask2.id}`,
-  to: mainTask,
-  type: 'child-of'
-})
-// 7. Subtask 2 depends on subtask 1
-await link({
-  from: `claude://current/${subtask1.id}`,
-  to: `claude://current/${subtask2.id}`,
-  type: 'blocks'
-})
-// 8. Check what's ready to work on
-const ready = await query({ find: 'ready' })
-// Returns subtask1 (subtask2 is blocked)
-// 9. Work on subtask 1 (using Claude Tasks)
-TaskUpdate({ taskId: subtask1.id, status: 'in_progress', owner: 'agent-1' })
-// ... do work ...
-TaskUpdate({ taskId: subtask1.id, status: 'completed' })
-// 10. Now subtask2 is ready
-const nowReady = await query({ find: 'ready' })
-// Returns subtask2
-// 11. Add feedback on the context after implementation
-await annotate({
-  target: prdUri,
-  source: mainTask,
-  feedback: {
-    content: 'Implemented Google OAuth. GitHub OAuth requires additional scopes - created follow-up task.',
-    type: 'comment',
-    anchor: { section: 'OAuth Providers' }
-  }
-})
-// 12. Update Beads task status (using bd CLI)
-// $ bd update bd-x7k9 -s closed
-```
----
-## Error Handling
-```typescript
-interface OpenTasksError {
-  code: ErrorCode
-  message: string
-  details?: Record<string, unknown>
-}
-type ErrorCode =
-  | 'NOT_FOUND'           // URI doesn't resolve
-  | 'INVALID_URI'         // Malformed URI
-  | 'UNKNOWN_PROVIDER'    // No provider for URI scheme
-  | 'VALIDATION_ERROR'    // Invalid parameters
-  | 'CYCLE_DETECTED'      // Would create circular blocks dependency
-  | 'PROVIDER_ERROR'      // Provider failed
-  | 'STORAGE_ERROR'       // Persistence failure
-```
-**Examples:**
-```typescript
-// Self-referencing edge
-link({ from: 'beads://./bd-x7k9', to: 'beads://./bd-x7k9', type: 'blocks' })
-// Error: { code: 'VALIDATION_ERROR', message: 'Cannot create self-referencing edge' }
-// Circular dependency
-link({ from: 'beads://./bd-c', to: 'beads://./bd-a', type: 'blocks' })
-// (when bd-a blocks bd-b, bd-b blocks bd-c)
-// Error: { code: 'CYCLE_DETECTED', message: 'Would create circular dependency',
-//          details: { cycle: ['bd-a', 'bd-b', 'bd-c', 'bd-a'] } }
-// Unknown provider
-query({ find: 'resolve', node: 'unknown://foo' })
-// Error: { code: 'UNKNOWN_PROVIDER', message: 'No provider registered for scheme: unknown' }
-```
----
-## Native System Integration
-OpenTasks doesn't replace native systems — it connects them. Here's how each system fits:
-### Claude Code Tasks
-| Aspect | Handling |
-|--------|----------|
-| **CRUD** | Use native `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` |
-| **URI scheme** | `claude://[session]/[task-id]` |
-| **Linking** | Use OpenTasks `link` to connect to other systems |
-| **Feedback** | No native comments; use OpenTasks `annotate` |
-### Beads
-| Aspect | Handling |
-|--------|----------|
-| **CRUD** | Use `bd` CLI or Beads API |
-| **URI scheme** | `beads://[workspace]/[id]` |
-| **Linking** | Native deps for same-system; OpenTasks for cross-system |
-| **Feedback** | Native comments for same-system; OpenTasks for cross-system |
-### Taskmaster
-| Aspect | Handling |
-|--------|----------|
-| **CRUD** | Use `tm` CLI or Taskmaster API |
-| **URI scheme** | `taskmaster://[project]/[id]` |
-| **Linking** | Use OpenTasks for all relationships |
-| **Feedback** | Use OpenTasks `annotate` |
----
-## Status Mapping
-Different systems have different status models. OpenTasks uses canonical statuses for cross-system queries:
-| Canonical | Meaning | Maps From |
-|-----------|---------|-----------|
-| `open` | Not started | Claude `pending`, Beads `open`/`pinned`, Linear `Backlog` |
-| `in_progress` | Active work | Claude `in_progress`, Beads `in_progress`, Linear `In Progress` |
-| `blocked` | Waiting | Beads `blocked`/`hooked`/`deferred`, Linear `Blocked` |
-| `closed` | Done | Claude `completed`, Beads `closed`, Linear `Done`/`Cancelled` |
-The original provider status is preserved in `provider_status` for display.
----
-## Open Questions
-- [ ] **Session URIs**: How to handle `claude://current/...` when session changes?
-- [ ] **Cache invalidation**: When to refresh node metadata from providers?
-- [ ] **Bulk operations**: Should `link` and `annotate` support batching?
-- [ ] **Event subscriptions**: Should tools support watching for changes?
-- [ ] **Offline mode**: Behavior when providers are unavailable?
----
-## Version History
-| Version | Date | Changes |
-|---------|------|---------|
-| 0.2.0 | 2025-01-27 | Reframed as graph connector; 3-tool interface |
-| 0.1.0 | 2025-01-26 | Initial draft |